billproof is a free command-line tool that reads the Claude Code, Codex and Gemini CLI transcripts already on your disk, prices every request the way the provider bills it, and tells you which turns cost the money and why. Nothing leaves your machine.
| category | tokens | cost | share |
|---|---|---|---|
| uncached input | 510k | $3.52 | 0.0% |
| cache write 5m (1.25x) | 90.4M | $667.26 | 5.3% |
| cache write 1h (2x) | 120.5M | $1,458.92 | 11.6% |
| cache read (0.1x) | 16.01B | $9,367.24 | 74.5% |
| output | 35.4M | $1,076.56 | 8.6% |
| what a naive counter reports | total | error | |
| sums every transcript line | $27,773.46 | +121.0% | |
| every cache write priced as 5-minute | $12,020.86 | −4.4% | |
| cache tokens priced as input | $96,481.71 | +667.6% | |
| cache tokens ignored | $1,078.25 | −91.4% | |
Real output from the author's machine. Prices from platform.claude.com/docs/en/about-claude/pricing, fetched 2026-09-02.
Claude Code writes the exact usage object Anthropic billed into every transcript. The numbers are all there. Reading them correctly is the hard part.
Claude Code writes one JSONL line per content block, each repeating the full usage. Thinking + text + tool call = counted three times by anything that sums lines. billproof dedupes by message id.
A 5-minute cache write is 1.25x base. A 1-hour write is 2x. More than half of all turns on this machine used the 1-hour tier. Pricing everything at 1.25x under-reports every one of them.
Ignore reads and you under-report by ~90%. Price them as input and you over-report by ~670%. Both mistakes have shipped in real tools this year; the fixes were merged by the author of this one.
npx billproof reads the transcripts already on your disk and prices every request at list price, including both cache-write tiers and cache reads.billproof receipt --last lists every turn as a line item with its root cause: cache expired, one-hour writes, model switch, prefix changed, fast mode or server-side fallback.ccusage is the free CLI most people reach for, and it prices Claude Code sessions correctly: its source, read on 2 September 2026, applies the 2x rate to one-hour cache writes and de-duplicates transcript lines by request id. billproof exists for the questions that come after the total.
| question | ccusage | billproof |
|---|---|---|
| What did my sessions cost, with both cache-write tiers and cache reads priced? | yes; free; Claude Code, Codex, Gemini CLI and a dozen other agents | yes; free scan; Claude Code, Codex and Gemini CLI |
| Which turn cost the money, and why? | totals by day, session, model and billing block | a receipt: every turn as a line item with a root cause (cache expired, one-hour writes, model switch, prefix changed, fast mode, server-side fallback) |
| How far off would a naive counter have been? | not shown | four naive methods and each one's error, measured on your own transcripts |
| Does the Anthropic invoice match our own records? | not a feature | reconcile: the organisation's usage and cost reports against local records, day by day and model by model, every difference labelled by cause |
| Price | free | scan free; receipt $49 once; reconcile $199 once per organisation |
The free scan tells you the true number. The receipt tells you what caused it, turn by turn, with the dollars each cause explains and the evidence fields that fired the rule.
| cause | turns | attributed | meaning |
|---|---|---|---|
| context-heavy | 4,308 | $987.04 | large context read on every turn |
| subagent | 1,482 | $119.71 | work done by subagents |
| cache-expired | 14 | $50.73 | idle past the TTL; whole context re-written at write price |
| one-hour-write | 3,926 | $50.72 | 1-hour writes cost 2x base, 5-minute 1.25x |
| # | gap | w1h | read |
| 406 | 9h idle | 600k | 0 |
| 1961 | 1h idle | 783k | 0 |
| 386 | 3m | 592k | 0 |
Turn 386 re-wrote 592k tokens three minutes after the previous turn, with zero cache reads. That is not an expiry; the prompt prefix changed. billproof labels it prefix-changed.
| cause | rule, in plain words |
|---|---|
| cache-expired | Idle longer than the cache TTL of the previous write, then most of the context re-written. Attributed: the write-minus-read premium on every re-written token. |
| prefix-changed | Re-written inside the TTL with few reads. Compaction, an edited system prompt or a changed tool list broke the cached prefix. |
| one-hour-write | The 0.75x premium of the 1-hour tier over the 5-minute tier, on every 1-hour token. |
| model-switch | Caches are per model. Switching re-writes the context. |
| context-heavy | 100k+ tokens of context read on the turn. The reads themselves. |
| output-heavy · uncached-paste | 8k+ output tokens; 20k+ uncached input tokens (a paste, an image). |
| subagent · fast-mode · us-only-geo · fallback | Subagents on their own cache lane; the 2x fast-mode premium; the 1.1x US-only premium; a server-side fallback that billed the declining model's partial output. |
billproof activate <key>.~/.claude/projects locally and write nothing anywhere else. The only network call the tool ever makes is validating a license key when you run activate. The source is public so you can check.price-unverified whenever they are used instead of being silently guessed.billproof activate <key>. The checkout is a merchant of record, so EU and UK VAT is handled on the invoice you receive.