token-budget

Where your Claude Code token quota actually went — and what to change.

Ships one tool and three skills. Everything runs offline against the session transcripts Claude Code already writes to ~/.claude/projects/**/*.jsonl. No network, no npm, stdlib Python only.

Install

claude plugin add https://claude-plugins.oleks.space/plugins/token-budget.git

The finding it exists to surface

On heavy agentic usage the token split looks like this:

Category	% of raw tokens	% of cost
cache_read (context re-read)	~95%+	~60%
cache_write	~3%	~30%
output (what Claude generates)	<1%	~10%

Quota goes to re-reading context, not to writing answers. Every turn re-sends the whole conversation, so spend scales with (session length × context size) — largely independent of how much useful work a turn did. A session left alive for days pays for its entire accumulated history on every single turn.

That reframes the usual instinct ("Claude is too verbose") to the actual cause, and points at the two levers that matter: session lifecycle, and per-turn payload size.

Tool — cc-tokens

cc-tokens hogs           # diagnosis: names sessions AND the fix   (start here)
cc-tokens composition    # token/cost split by category — the "why"
cc-tokens sessions       # ranked culprits, with project + lifespan
cc-tokens daily          # per-day trend
cc-tokens projects       # per-project rollup
cc-tokens models         # per-model rollup
cc-tokens context --session <prefix>   # context-growth curve for one session

Flags: --days N / --since YYYY-MM-DD / --until, --top N, --json, --root PATH. Default window is 7 days. Runs in a few seconds over a multi-gigabyte history.

hogs flags four things and ranks them by spend:

Finding	Meaning
marathon-session	Alive ≥2 days; every turn re-reads an ever-growing context
bloated-context	Peak context >300k re-sent per turn
subagent-heavy	>50% of turns are subagents, each with its own full context
model-switching	Several models in one session — each switch invalidates the whole cached prefix

Skills

Skill	Role
token-audit	Diagnosis — run the audit, read the numbers, report honestly
session-hygiene	Fix #1 — when to /clear, how many concurrent sessions, how to size fan-out
context-diet	Fix #2 — shrink MCP tool schemas, CLAUDE.md, dumped file content; stop invalidating the cache

Plus a usage-agent that routes between them.

Quota vs cost

cc-tokens reports API-equivalent dollars, useful for ranking consumers. It is not your subscription quota and cannot predict when you hit the weekly cap — for the real bars, run /usage inside Claude Code.

Accuracy

Two transcript traps that make naive parsers wrong, both handled:

1. One message spans many JSONL lines. Claude Code appends a line per content block (thinking, text, each tool_use) and every line repeats the same message-level usage. Summing lines inflates a turn several-fold.
2. output_tokens grows across those lines — they are streaming snapshots of one response. Only the last is complete, so take the max per (message.id, requestId), not the first.

That key is also stable across files, so resumed, forked, and worktree-replayed sessions are not double-counted. <synthetic> entries (Claude Code's placeholders for API errors and interrupts) carry no tokens and are excluded.

Validated against ccusage on a full day: $1,311 vs $1,310.65, output 6.4M vs 6,391,730.

Pricing table

Rates are baked into bin/cc-tokens (PRICES) as of 2026-07-22. Cache multipliers on the input rate: read 0.1×, write 1.25× at the 5-minute TTL and 2× at the 1-hour TTL — Claude Code writes at 1h, which is why cache invalidation is the expensive event. Update PRICES when rates change.

License

MIT