AI coding cost and token tracking

A coding agent bills on tokens, not on the time you spent watching it work. Duration answers "how long was this session"; token usage answers "what did this session consume". Both are recorded here, on the same timeline, so a project can be read as time spent and as spend incurred.

The four token classes

• Input tokens: what was sent to the model
• Output tokens: what the model generated
• Cache read tokens: prompt content served from cache, billed at a lower rate
• Cache write tokens: content written into the cache, billed at a higher rate

They are stored separately because they are priced separately. Collapsing them into one number makes a cache-heavy session look identical to one that re-sent its whole context, and those two sessions do not cost the same.

Usage events arrive on a dedicated endpoint that carries identifiers and counts only. There is no prompt, response, patch, file path or source-code field in the payload.

[
  {
    "usage_event_id": "msg_01ExampleProviderMessageId",
    "ai_session_id": "your-session-id",
    "occurred_at": "2026-08-23T04:15:00Z",
    "agent": "claude-code",
    "provider": "anthropic",
    "model": "your-model-name",
    "prompt_count": 1,
    "input_tokens": 18450,
    "output_tokens": 1220,
    "cache_read_tokens": 96300,
    "cache_write_tokens": 4100,
    "token_source": "reported"
  }
]

Events are keyed by the provider’s own message id, so replaying a transcript cannot double-count a session. Bundled hooks read this from each agent’s local transcript; you can also post it from your own wrapper.

• Claude Code, Codex CLI and Gemini CLI have bundled hooks that read their local transcripts
• Any other tool can post to the same endpoint directly
• Cursor and Copilot need a provider-specific adapter before their usage can be attributed

A tool with no hook and no adapter is not reported as zero usage. It is simply absent, and the coverage figures show how much of the period that absence accounts for.

Cost is derived, never guessed. Each provider and model pair has price rows with an effective window, so an event is priced with the rate that was actually in force when it happened rather than with today’s rate.

The rules that keep the number honest

• Pricing is selected by provider and model together, never by model name alone — two providers can publish the same model label at different rates
• Each price row carries an effective-from date and a version, so a repricing does not silently rewrite last month
• Amounts are held in micro-USD to avoid rounding drift across millions of events
• An unknown provider or model produces an unknown cost, not a cost of zero

The shipped catalogue covers Anthropic list prices. Usage from a provider with no price row still reports its tokens — you keep the consumption figure and lose only the money figure.

Usage events carry the agent’s workspace context, reduced to a project name before it leaves your machine, so spend can be grouped the same way coding time is.

When an event has no explicit project

• If every other event in that session belongs to one project, the event inherits it
• If the session touched more than one project, the event stays unattributed rather than being copied into all of them

The second rule is why a project total can be lower than the account total. Splitting an ambiguous session across projects would make every project look more expensive than it was, and there would be no way to tell which part was invented.

Attribution, tokens and estimated spend each carry their own coverage percentage, and a value that cannot be derived is returned as null with that coverage attached.

{
  "tokens":          { "total": 1204300, "coverage_percent": 92.4 },
  "estimated_spend": { "amount_microusd": 3184500, "coverage_percent": 74.1, "currency": "USD" },
  "coverage":        { "attribution_percent": 88.0, "token_percent": 92.4, "cost_percent": 74.1 }
}

A dashboard that renders an unknown as 0 is telling you something it does not know. Reading "74% priced" tells you how far to trust the total, and a subscription plan that never exposes per-call pricing is visibly out of scope rather than quietly counted as free.

• Prompts, model responses and conversation transcripts
• Source file contents and patches
• Absolute paths — only the final directory name is used as the project label

The usage stream is numeric and identifier-only by design. Prompt length is counted locally and only the character count is sent; the prompt text itself is discarded on your machine.

• Estimated cost is a list-price estimate, not an invoice, and will not match a bill that includes negotiated or subscription terms
• A subscription plan with no per-call pricing produces tokens without a cost figure
• Usage arrives only from agents with a hook or an adapter
• Historical events keep the price that was effective when they happened; changing the catalogue does not restate them