Build on ClockMe

REST API, 20 MCP tools, and hook integrations — everything you need to wire ClockMe into any AI coding tool or automation.

Quickstart

Three curl commands to get a timer running.

curl -X POST https://clockme.co/api/timer/start \
  -H "Authorization: Bearer ck_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"projectName":"my-project","fallbackProjectId":"PROJECT_ID"}'

curl https://clockme.co/api/timer/current \
  -H "Authorization: Bearer ck_live_YOUR_KEY"

curl -X POST https://clockme.co/api/timer/stop \
  -H "Authorization: Bearer ck_live_YOUR_KEY" \
  -H "Content-Length: 0"

Authentication

All requests use a Bearer token. Generate keys in Setup or Settings → API Keys.

Authorization: Bearer ck_live_YOUR_KEY

REST API

Base URL: https://clockme.co. Full schema at /api/openapi.

API Explorer

Pick an endpoint, paste your API key, edit the request, and run it against the live API. Destructive verbs require confirmation. All calls go to https://clockme.co and read/write your real account.

MCP tools

20 tools exposed via Model Context Protocol at https://clockme.co/api/mcp. Compatible with Claude Code, Cursor, Windsurf, GitHub Copilot, and Gemini CLI.

// ~/.claude/settings.json (Claude Code)
{
  "mcpServers": {
    "clockme": {
      "type": "http",
      "url": "https://clockme.co/api/mcp",
      "headers": { "Authorization": "Bearer ck_live_YOUR_KEY" }
    }
  }
}

Hooks

Three hook events wire ClockMe into Claude Code's session lifecycle: SessionStart auto-starts a timer — the folder name ($CLAUDE_PROJECT_DIR) fuzzy-matches a ClockMe project, and autoCreate makes a project named after the folder if there's no match, so the hook never fails. UserPromptSubmit sends a heartbeat each turn, and SessionEnd stops the timer on clean exit. A server-side watchdog auto-stops idle MCP/hook timers after 30 min by default. Install once globally — every repo is tracked with zero per-project setup.

Do not use the Stop event for stopping — it fires after every assistant response, not at session end. Use SessionEnd.

// ~/.claude/settings.json
{
  "mcpServers": {
    "clockme": {
      "type": "http",
      "url": "https://clockme.co/api/mcp",
      "headers": {
        "Authorization": "Bearer ck_live_YOUR_KEY"
      }
    }
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -sf --max-time 10 -X POST https://clockme.co/api/timer/start -H 'Authorization: Bearer ck_live_YOUR_KEY' -H 'Content-Type: application/json' -d \"{\\\"projectName\\\":\\\"$(basename \"$CLAUDE_PROJECT_DIR\")\\\",\\\"autoCreate\\\":true,\\\"source\\\":\\\"hook\\\",\\\"description\\\":\\\"Claude Code session\\\"}\" > /dev/null",
            "shell": "bash"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -sf --max-time 10 -X POST https://clockme.co/api/timer/stop -H 'Authorization: Bearer ck_live_YOUR_KEY' -H 'Content-Type: application/json' -d \"{\\\"projectName\\\":\\\"$(basename \"$CLAUDE_PROJECT_DIR\")\\\"}\" > /dev/null",
            "shell": "bash"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "curl -sf --max-time 10 -X POST https://clockme.co/api/timer/heartbeat -H 'Authorization: Bearer ck_live_YOUR_KEY' -H 'Content-Type: application/json' -d '{}' > /dev/null",
            "shell": "bash"
          }
        ]
      }
    ]
  }
}

Requires curl — pre-installed on macOS and Linux; winget install curl on Windows. Prefer routing unmatched folders to one pinned project instead of creating new ones? Swap "autoCreate":true for "fallbackProjectId":"YOUR_PROJECT_ID" in the start command. Use the Setup wizard to generate either variant with your key pre-filled.

Hooks not firing on Windows? Claude Code runs these commands through Git Bash, which it looks for in C:\Program Files\Git. If Git is installed anywhere else, hooks die silently with "Git Bash was not found". Fix: set the CLAUDE_CODE_GIT_BASH_PATH environment variable to your bash.exe (e.g. setx CLAUDE_CODE_GIT_BASH_PATH "D:\Tools\Git\bin\bash.exe"). To see what your hooks are actually doing, run claude --debug-file hooks.log and check the log for hook errors.

Workspaces & teams

Every account has a personal workspace; you can create shared ones and invite teammates with a link. Projects, tasks, and budgets belong to a workspace — every member sees them. Time entries stay personally authored: members can readeach other's entries, but an entry can only be created or edited by its author. Two roles: owner (manages invites and members) and member.

API calls are scoped to your active workspace: project and task lists are workspace-wide, while timer control and "my hours" reports stay personal. The clockme_get_team_summary MCP tool and GET /api/workspaces/{id}/summaryaggregate hours by member and by project — in a solo workspace that's just your own hours.

# Who's logged what this month?
curl https://clockme.co/api/workspaces/WORKSPACE_ID/summary?from=2026-06-01&to=2026-06-30 \
  -H 'Authorization: Bearer ck_live_YOUR_KEY'

# List workspaces you belong to (IDs, roles, member counts)
curl https://clockme.co/api/workspaces \
  -H 'Authorization: Bearer ck_live_YOUR_KEY'

Manage your team — invites, members, switching workspaces — from the Team page in the dashboard.

Integrations

Step-by-step setup for each AI coding tool.

Also see: all integrations (GitHub, Linear, Notion, Zapier, Slack).

FAQ

Can't find your answer? Email us.