Codex Setup

One-command setup for automatic time tracking in OpenAI Codex.

Overview

TeeckIn integrates with OpenAI Codex to automatically track your development time. Setup takes less than a minute with our NPM package.

What you get:

+Codex asks what topic you're working on at session start
+MCP tools for seamless time tracking control
+Switch topics mid-session by asking Codex

Quick Setup

Two steps to get started:

1. Create an Agent

Go to Settings → Automation → Agents and create a new agent:

- Select Codex as type
- Give it a name (e.g., "My Codex Agent")
- Copy both the Client ID and Client Secret

Save Your Secret Now

The Client Secret is only shown once! Copy it immediately after creating the agent. You can always see the Client ID later, but not the secret.

2. Run Setup

bash

# Run in your project directory
npx @teeckin/agent init --codex

# The CLI will prompt for your credentials

Your credentials are saved securely in the local config files.

Personal vs Billing entity

Create a personal agent in Settings → Automation → Agents for solo projects. For team projects, use a billing entity agent from Settings → Automation → Agents (with the billing entity selected).

What Gets Created

The setup command creates these files:

~/.codex/config.toml

MCP server configuration (user-level, shared across projects)

.codex/hooks.json

Project-level hooks for session events

AGENTS.md

Instructions for Codex to prompt for topics

One Agent, Multiple Projects

You can use the same agent credentials across multiple projects. Just run npx @teeckin/agent init --codex in each project directory.

Security

Keep Secrets Secure

The config.toml file contains your credentials in ~/.codex/. Keep this directory secure.

Secret Rotation

You can create up to 5 secrets per agent for zero-downtime rotation. Go to Settings → Automation → Agents, expand your agent, and click "New Secret" in the Secrets tab. Then run npx @teeckin/agent init again to update your local config.

CLI Commands

The package provides commands for setup and manual timer control:

Config Commands

npx @teeckin/agent initInitial setup (creates files, prompts for credentials)

npx @teeckin/agent authUpdate credentials (for secret rotation)

npx @teeckin/agent updateRefresh config with latest MCP tools and features

Timer Commands

npx @teeckin/agent exec:statusCheck if a timer is running

npx @teeckin/agent exec:update "notes"Update notes on the active timer

npx @teeckin/agent exec:stopManually stop the active timer

Updating After TeeckIn Releases

When TeeckIn adds new MCP tools or features, run npx @teeckin/agent update to refresh your configuration without re-entering credentials.

Available Tools

Once configured, Codex has access to these MCP tools:

Timer Control

teeckin_get_statusCheck timer status; detects recent sessions for resume

teeckin_list_topicsList available topics and categories

teeckin_start_timerStart tracking time on a topic (includes followup items)

teeckin_stop_timerStop the active timer

teeckin_log_timeLog a completed time entry retroactively

Checklist Tracking

teeckin_add_checklist_itemAdd a task to track on the active timer

teeckin_check_itemMark a task as done (fuzzy matching)

teeckin_uncheck_itemReopen a completed task

teeckin_get_followupSee incomplete tasks from last session

teeckin_accept_followupCarry over incomplete tasks to current session

Notes & Tags

teeckin_update_timerUpdate notes on the active timer (text mode)

teeckin_list_tagsList available tags for categorizing work

teeckin_add_tagsAdd tags to the active timer (creates if needed)

Checklist Mode

Codex can track work as a checklist of tasks, checking them off as it goes. This creates a living document of what was accomplished during the session.

When tasks are added, Codex tracks them on the active timer. As work completes, it checks off items using fuzzy matching. The checklist persists with the time entry, giving you a record of exactly what was done.

Timer running: Project Alpha (45 minutes)

Checklist (2/3 done):

- [x] Fix login validation bug

- [x] Add unit tests

- [ ] Update documentation

Session Resume

If you start a new session within 10 minutes of stopping, Codex detects this and offers to resume your previous session.

This prevents losing context when you clear a conversation to start fresh but want to keep working on the same topic. The teeckin_get_status tool returns recent session info including incomplete tasks.

No timer running.

Recent session available:

- Topic: API Development

- Stopped: 3 minute(s) ago

- Incomplete tasks: 1

Ask user if they want to resume.

Followup Between Sessions

If a session ends with incomplete tasks, they're saved. When starting a new session on the same topic, Codex can carry them over automatically.

Use teeckin_get_followup to check for incomplete items from the last session, then teeckin_accept_followup to add them to the current checklist.

Automatic Workflow

The AGENTS.md instructions tell Codex to check for followup items at session start and ask if you want to carry them over.

Config.toml Reference

The MCP server is configured in your user config with OAuth authentication:

toml

# ~/.codex/config.toml

[mcp_servers.teeckin]
url = "https://api.teeckin.com/api/mcp"
required = false
oauth_client_id = "teeckin_agent_..."
oauth_client_secret = "tcs_..."

Troubleshooting

Codex doesn't ask about topics

Make sure the AGENTS.md file was created. Check if TeeckIn section exists at the bottom.

MCP tools not available

Check ~/.codex/config.toml has the [mcp_servers.teeckin] section with valid credentials.

'Authentication failed' during init

Verify your credentials in Settings → Automation → Agents. If the secret was lost, create a new one in the Secrets tab.

'invalid_client' error

Check credentials in ~/.codex/config.toml. The client_id starts with 'teeckin_agent_' and client_secret starts with 'tcs_'. Run init again to re-enter them.

Was this helpful?