npm package: @kodocodes/claude-code
Description: Kodo plugin for Claude Code — track your AI coding sessions
Author: usmangurowa
Latest version: 0.1.7

# Kodo for Claude Code

Track your agentic coding sessions from [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) with [Kodo](https://kodo.codes).

## Installation

### Option A — npx (recommended)

```bash
npx @kodocodes/claude-code setup
```

`setup` will:

1. Ask for your API key (find it at [kodo.codes/dashboard/settings/api-keys](https://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](https://code.claude.com/docs/en/plugins):

```bash
claude plugin marketplace add https://github.com/usmangurowa/kodo-claude.git
claude plugin install @kodocodes/claude-code@kodo
npx @kodocodes/claude-code setup
```

Run `npx @kodocodes/claude-code 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`:

```json
{
  "api_key": "kodo_your_api_key_here"
}
```

### Hook registration

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

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

---

## 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-code`

**Testing the hook manually:**

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

**Development:**

```bash
# In apps/claude
pnpm build:watch      # rebuilds on save
npm link              # installs locally; then run: @kodocodes/claude-code setup
```