@teeckin/agent

One-command setup for TeeckIn time tracking in AI coding agents.

Supports Claude Code and OpenAI Codex.

Quick Start

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

The CLI auto-detects your agent type. You can also specify explicitly:

npx @teeckin/agent init --claude   # Claude Code
npx @teeckin/agent init --codex    # OpenAI Codex

Authentication

Claude Code (Browser-based)

Claude Code uses OAuth PKCE flow - no credentials needed in config files. When you start a Claude Code session:

1. Claude connects to TeeckIn MCP server
2. Your browser opens to TeeckIn for authorization
3. You select or create an agent to use
4. Authorization completes automatically

Codex (OAuth Credentials)

Codex requires OAuth credentials from TeeckIn Settings > Agents:

1. Create an agent at teeckin.com/app/agents
2. Copy the Client ID and Client Secret
3. Run npx @teeckin/agent init --codex and enter the credentials

Or set environment variables:

export TEECKIN_CLIENT_ID=teeckin_agent_...
export TEECKIN_CLIENT_SECRET=tcs_...
npx @teeckin/agent init --codex

What It Does

For Claude Code

Creates:

• .mcp.json - MCP server configuration (PKCE auth via browser)
• .claude/settings.json - SessionEnd hook to auto-stop timer
• CLAUDE.md - Instructions for Claude to prompt for topics

For Codex

Creates:

• ~/.codex/config.toml - MCP server configuration with OAuth credentials
• .codex/hooks.json - Session hooks
• AGENTS.md - Instructions for Codex to prompt for topics

Commands

Config commands (manage MCP setup):

npx @teeckin/agent init              # Initial setup (prompts for token)
npx @teeckin/agent update            # Update MCP config with latest features
npx @teeckin/agent help              # Show help

Timer commands (interact with API):

npx @teeckin/agent exec:status           # Check if timer is running
npx @teeckin/agent exec:update "notes"   # Update notes on active timer
npx @teeckin/agent exec:stop             # Stop the active timer

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | TEECKIN_CLIENT_ID | Codex only | OAuth Client ID (from Settings > Agents) | | TEECKIN_CLIENT_SECRET | Codex only | OAuth Client Secret | | TEECKIN_API_URL | No | Custom API URL (for self-hosted) |

How It Works

1. Session starts - Agent asks what topic you're working on
2. You pick a topic - Timer starts automatically
3. You work - Time is tracked in the background
4. Session ends - Timer stops automatically (via hooks)

Switch topics mid-session by telling your agent.

Requirements

• Node.js 18+
• Pro subscription (personal agents) or Team plan (organization agents)

Links

• Documentation
• TeeckIn Website
• GitHub

License

MIT