Kodo for Claude Code

Track your agentic coding sessions from Claude Code CLI with Kodo.

Installation

Option A — npm (recommended)

npm install -g kodo-claude
kodo-claude setup

setup will:

1. Ask for your API key (find it at kodo.codes/dashboard/settings/api-keys) and save it to ~/.kodo/config.json
2. Automatically register the required hooks in ~/.claude/settings.json

That's it. Start Claude Code — your sessions are tracked.

Option B — Claude plugin marketplace

If you use the Claude Code plugin system:

/plugin marketplace add usmangurowa/kodo-claude
/plugin install kodo-claude@kodo
kodo-claude setup

Run kodo-claude setup after installing to configure your API key.

Manual setup (optional)

If you prefer to configure things by hand:

API key

Create ~/.kodo/config.json:

{
  "api_key": "kodo_your_api_key_here"
}

Hook registration

Add the following to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "kodo-claude" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "kodo-claude" }]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "kodo-claude" }]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "kodo-claude" }]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "kodo-claude" }]
      }
    ]
  }
}

Configuration reference

| Setting | Description | Default | | -------------------------------------- | --------------------------------------- | ------------------------ | | ~/.kodo/config.json → api_key | Your Kodo API key | — | | ~/.kodo/config.json → api_endpoint | Custom API endpoint | https://api.kodo.codes | | KODO_API_KEY env var | API key (overrides config file) | — | | KODO_API_ENDPOINT env var | Custom endpoint (overrides config file) | — |

How it works

The plugin hooks into Claude Code's event system. On each hook event:

1. Reads the session transcript to identify files modified by Claude since the last heartbeat.
2. Counts AI line changes from structured patches.
3. Sends heartbeats to the Kodo API with file, project, language, and branch metadata.
4. Persists state per-session (throttles to one heartbeat per minute).

Heartbeats are automatically tagged with editor: "claude-code" so they appear under the Claude Code integration in your Kodo dashboard.

Troubleshooting

No data appearing in Kodo dashboard:

• Verify your API key: cat ~/.kodo/config.json
• Check Claude Code is using the hook: claude --debug
• Ensure the binary is in your $PATH: which kodo-claude

Testing the hook manually:

echo '{"session_id":"test","transcript_path":"/tmp/test.jsonl","cwd":"'$PWD'","hook_event_name":"UserPromptSubmit"}' | kodo-claude

Development:

# In apps/claude
pnpm build:watch   # rebuilds on save
npm link           # exposes the local build as kodo-claude in your $PATH

Testing the hook manually:

echo '{"session_id":"test","transcript_path":"/tmp/test.jsonl","cwd":"/your/project","hook_event_name":"UserPromptSubmit"}' | kodo-claude