Claude Code Setup

One-command setup for automatic time tracking in Claude Code.

Overview

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

Browser-Based Authentication

Claude Code uses OAuth 2.0 with PKCE - a secure, browser-based authentication flow. This means:

✓No API keys or secrets to manage
✓No credentials stored in project files
✓Authenticate once, works across all projects

What you get:

+Claude asks what topic you're working on at session start
+Ask Claude to stop the timer when you're done
+Switch topics mid-session by asking Claude

Quick Setup

One command to get started:

Run Setup

bash

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

No credentials needed! Authentication happens in your browser.

First Connection

When Claude Code first connects to TeeckIn, your browser will open automatically:

1.Sign in to TeeckIn (if not already logged in)
2.Select an existing agent or create a new one
3.Click "Authorize" to grant permissions
4.Return to Claude Code - you're connected!

Different from Other AI Tools

Unlike Cursor, Copilot, or other AI tools that require API keys (Client ID + Secret), Claude Code uses browser-based OAuth. You don't need to create secrets in TeeckIn or store credentials in your project. Other AI tools that don't support this method will need to use the Client Credentials flow.

Personal vs Organization

During the browser authorization, you can choose any agent you have access to - personal agents or organization agents.

What Gets Created

The setup command creates these files in your project:

.mcp.json

MCP server URL (no credentials - auth happens via browser)

.claude/settings.json

SessionEnd hook and MCP tool permissions

CLAUDE.md

Instructions for Claude to prompt for topics

Safe to Commit

The .mcp.json file only contains the server URL - no secrets. You can safely commit it to version control.

Per-Project Agents

By default, Claude Code authenticates once and uses the same agent across all projects. If you want different agents for different projects (e.g., separate time tracking for client work), you have two options.

Option 1: Local Scope (Recommended)

Use Claude Code's "local" scope to configure TeeckIn per-project without modifying the project's .mcp.json. This is ideal when working on client codebases where you don't want to add your own config files.

Add a unique query parameter to differentiate the URL per project:

bash

# In project A
cd ~/projects/project-a
claude mcp add teeckin -s http -t streamable-http \
  --url "https://api.teeckin.com/api/mcp?project=project-a"

# In project B
cd ~/projects/project-b
claude mcp add teeckin -s http -t streamable-http \
  --url "https://api.teeckin.com/api/mcp?project=project-b"

The query parameter (?project=...) makes Claude Code treat each URL as a separate MCP server, triggering separate OAuth flows. The server ignores the parameter - agent selection happens during the browser authorization.

How Local Scope Works

Local scope stores configuration in your personal ~/.claude.json file, organized by project path. It's not committed to the project repository, so you can use it on client codebases without modifying their files.

Option 2: Project-Level Config

If you control the project, run the setup command with a unique URL:

bash

# Creates .mcp.json in the project
TEECKIN_API_URL="https://api.teeckin.com/api/mcp?project=my-project" \
  npx @teeckin/agent init --claude

This creates a .mcp.json file that can be committed to version control. Team members will each authenticate with their own agent during the browser flow.

Switching Agents

To switch which agent a project uses, run in Claude Code. Your browser will open and you can select a different agent.

Ending Sessions

When you're done working, ask Claude to stop the timer:

Ask Claude to stop the timer

Simply tell Claude: "Stop the timer" or . Claude will call the . Claude will call the tool.

Known Issue: SessionEnd hooks unreliable

Neither /exit nor reliably trigger SessionEnd hooks in Claude Code. This is a reliably trigger SessionEnd hooks in Claude Code. This is a we're waiting on Anthropic to fix. In the meantime, always ask Claude to stop the timer before ending your session.

Forgot to stop?

If you forget to stop the timer, the next session will detect it and offer to resume. Your time is preserved, not lost.

Security

Claude Code uses OAuth PKCE (Proof Key for Code Exchange) for secure authentication:

+No credentials stored in project files
+Authentication happens in your browser
+Tokens are stored securely by Claude Code
+You can revoke access anytime from Settings > Agents

Re-authorization

If you need to switch agents or re-authorize, use Claude Code's command. Your browser will open for fresh authorization.

CLI Commands

The package provides commands for setup and manual timer control:

Config Commands

npx @teeckin/agent initInitial setup (creates config files)

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 to refresh your configuration without re-entering credentials.

Available Tools

Once configured, Claude 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 the current topic (persists across sessions)

teeckin_start_itemStart working on a task (tracks time, auto-pauses others)

teeckin_check_itemMark a task as done (fuzzy matching)

teeckin_uncheck_itemReset a completed or dismissed task to pending

teeckin_dismiss_itemMark a task as not needed (preserves time spent)

teeckin_get_followupSee pending tasks on the current topic

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

Tasks are scoped to topics, not individual time entries. This means incomplete tasks persist across sessions until you complete or dismiss them. Time spent on each task is tracked when you start working on it.

You:

Fix the login validation bug and add unit tests

Claude:

[adds tasks, starts working on first]
I'll track these tasks:
- Fix login validation bug (starting now)
- Add unit tests for auth module

Claude (after fixing bug):

[checks off task]
Fixed the validation issue (12 min). Moving on to tests.

When you check status, the checklist shows states and time:

Timer running: Project Alpha (45 minutes)

Currently working on: Add unit tests (8 min)

Tasks (1/2 done):

- [x] Fix login validation bug (12 min)

- [*] Add unit tests for auth module (ongoing)

Auto-Pause

Only one task can be "ongoing" at a time. When Claude starts a new task, the previous ongoing task is automatically paused. This ensures accurate time tracking per task.

Session Resume

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

Claude (new session, within 10 min):

You were working on API Development 3 minutes ago.

Incomplete tasks:
- [ ] Add unit tests for auth module

Resume that session?

You:

Yes

Claude:

[starts timer on "API Development", carries over tasks]
Resumed! Ready to continue.

Quick Context Switch

This prevents losing context when you clear a conversation to start fresh but want to keep working on the same topic.

Task Persistence

Tasks persist on topics automatically. When you start a new session on the same topic, pending tasks are still there - no need to "carry over" or accept anything.

Claude (new session):

Timer started on "Project Alpha".

Pending tasks (1):
- [ ] Add unit tests for auth module

Ready to continue where you left off?

You:

Yes, let's do the tests

Claude:

[starts working on task]
Working on unit tests now.

Dismiss vs Complete

If a task is no longer relevant, ask Claude to dismiss it. This removes it from the pending list while preserving any time already spent on it.

Example Session

Claude (session start):

I see TeeckIn is configured. What topic are we working on today?

Available topics:
- Backend: API Development, Database
- Frontend: React Components, Styling

You:

API Development

Claude:

[starts timer on "API Development"]
Timer started! What would you like to work on?

You:

Add pagination to the users endpoint

Claude:

[implements the feature]
Done! I've added limit/offset pagination with a default of 20 items per page.

You:

Great, I'm done for today. Stop the timer.

Claude:

[stops timer]
Timer stopped. You worked 23 minutes on API Development today.

Troubleshooting

Claude doesn't ask about topics

Make sure the CLAUDE.md file was created. Check if TeeckIn section exists at the top.

Timer doesn't stop when session ends

SessionEnd hooks are currently unreliable in Claude Code (known Anthropic issue). Always ask Claude to stop the timer before ending your session.

Browser doesn't open for authorization

Try running /mcp reconnect teeckin in Claude Code. If that fails, check your default browser settings.

Authorization page shows error

Make sure you're logged in to TeeckIn. If the error persists, try clearing your browser cache for teeckin.com.

Want to switch to a different agent

Run /mcp reconnect teeckin in Claude Code. Your browser will open and you can select a different agent to authorize.