cc-hook

Claude Code hook and CLI for reporting token usage to cc-tracker.

It runs as a Claude Code hook after every response, reads token counts from the session transcript, and POSTs them to the cc-tracker server. It also provides a CLI (cc-hook) for viewing stats and annotating sessions from the terminal.

Install

git clone <repo>
cd cc-hook
go install ./cmd/cc-hook

This puts cc-hook in $GOPATH/bin (typically ~/go/bin). Make sure that is on your $PATH.

Config

Create ~/.config/cc-tracker/config.toml:

server_url = "https://your-cc-tracker-instance"
api_key    = "cctrk_<your key from the dashboard>"
machine    = "my-macbook"   # identifies this machine in the dashboard
model      = "claude-sonnet-4-6"  # fallback if CLAUDE_MODEL env var is not set

The api_key is generated in the cc-tracker dashboard under API Keys.

Claude Code hooks

Add the following to ~/.claude/settings.json (under the "hooks" key). Replace the binary path with wherever cc-hook was installed.

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/<you>/go/bin/cc-hook 2>/dev/null || true",
            "async": true
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/<you>/go/bin/cc-hook stop 2>/dev/null || true"
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/<you>/go/bin/cc-hook session-end 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

The hook fires on every prompt submit, reads the JSONL transcript to sum tokens per request (deduplicating streaming entries), and sends the totals to cc-tracker. It also writes the raw payload to /tmp/cc-hook-debug.json so cc-hook name and cc-hook upload-summary can pick up the current session ID.

If the server is unreachable, the request is saved to a retry queue at ~/.local/share/cc-tracker/failed.jsonl and can be replayed with cc-hook retry.

cc-hook CLI

cc-hook summary [--since 7d|30d|mtd|all]
    Print a token and cost summary for the given period.

cc-hook breakdown [--by machine|project|model] [--since 7d|30d|mtd|all]
    Print a cost breakdown grouped by machine, project, or model.

cc-hook budget
    Show monthly budget usage (limit configured on the server).

cc-hook name <session name>
    Name the current Claude Code session. Must be called from within
    an active session (or just after it ends) so the session ID is
    available in /tmp/cc-hook-debug.json.

cc-hook upload-summary <path/to/summary.md> [--repo <url>] [--branch <name>] [--pr <url>]
    Upload a markdown summary for the current session. Optional git
    metadata is shown in the dashboard alongside the summary.

cc-hook retry
    Replay any requests that failed to send while the server was unreachable.

/name-session and /summarize-session skills

These are Claude Code skills (in ~/.claude/ or the project's .claude/ dir) that prompt Claude to generate a session name or summary and then call cc-hook name / cc-hook upload-summary automatically.

• /name-session — generates a short descriptive name and sets it via cc-hook name
• /summarize-session — generates a markdown summary and uploads it via cc-hook upload-summary

The skills are defined in the Claude Code superpowers plugin and do not need to be configured manually on each machine — they come with the plugin.