cachemiss

Why did my Claude Code quota drain? One command over the transcripts Claude Code already keeps on your disk: every prompt-cache rebuild, why it happened, what it cost, and which sub-agent did it. Nothing leaves your machine.

pip install cachemiss
cachemiss                 # the last 5 hours, the quota window
cachemiss why             # each reason explained, with what to do about it
cachemiss session <id>    # one session as a timeline
cachemiss sessions        # sessions ranked by rebuild cost
cachemiss --since 7d --json

What it shows

A Claude Code session is a chain of API calls that share a growing prompt. In a healthy chain each call reads the whole prefix from the prompt cache and writes only the last turn. A rebuild is a call that writes again what the previous call had already cached: the cache entry expired, the tool list or system prompt changed, the history was compacted, or the model switched. A cold start is the first call of a chain (a new session, a sub-agent, a fork); nothing was cached yet, so it is priced separately and never counted as a rebuild. Rebuilds are where a five-hour window goes.

Real output from the machine this was written on, last 24 hours:

cachemiss  window: 24h   calls: 624   sessions: 34
prompt tokens: 152450k   cache hit rate: 97%   written: 3959k   uncached input: 12k   output: 692k
rebuilds: 10   tokens rewritten that were already cached: 986k   paid as writes: $18.08   as reads they would have cost: $0.25   rebuild premium: $17.83
Dollar figures are API list prices for the same tokens; a subscription quota is not billed in dollars, but it drains in the same proportion.
API diagnostics present on 7 calls; other reasons are inferred.

when        session  agent              reason                               gap      rewrote  premium
09-26 16:37 0f82a131 main               previous_message_not_found (gap>TTL) 3h00        374k    $7.38
09-26 08:50 e7185911 main               previous_message_not_found (gap>TTL) 14h40       369k    $7.29
09-26 17:33 0f82a131 general-purpose    subagent_start*                      -            47k    $0.58
09-26 17:33 0f82a131 general-purpose    subagent_start*                      -            47k    $0.57
09-26 12:31 0f82a131 general-purpose    subagent_start*                      -            47k    $0.57
09-26 17:33 0f82a131 general-purpose    subagent_start*                      -            47k    $0.57
09-26 17:45 0f82a131 general-purpose    subagent_start*                      -            30k    $0.37
09-26 09:50 ec11008d main               messages_changed                     12s          12k    $0.23
09-26 09:13 e7185911 main               messages_changed                     8s            9k    $0.17
09-26 10:25 ba739404 main               messages_changed                     2s            4k    $0.09
* = reason inferred from the record (no API diagnostics on that call)

by reason                                 n   rewrote  premium
previous_message_not_found (gap>TTL)      2      743k   $14.67
subagent_start*                           5      218k    $2.67
messages_changed                          3       25k    $0.50

by agent                                  n   rewrote  premium
main                                      5      768k   $15.16
general-purpose                           5      218k    $2.67

by session                                n   rewrote  premium
0f82a131 serialized-moseying-snowglobe    6      591k   $10.05
e7185911 synthetic-squishing-platypus     2      378k    $7.46
ec11008d                                  1       12k    $0.23
ba739404 majestic-puzzling-flask          1        4k    $0.09

by model                                  n   rewrote  premium
claude-fable-5-1                         10      986k   $17.83

cachemiss window: 24h calls: 650 sessions: 34 prompt tokens: 166521k cache hit rate: 97% written: 4187k uncached input: 12k output: 722k rebuilds: 5 tokens rewritten that were already cached: 739k paid as writes: $14.78 as reads they would have cost: $0.18 rebuild premium: $14.59 cold starts (not rebuilds): 38, of which 6 sub-agents; written: 1270k paid: $12.66 Dollar figures are API list prices for the same tokens, a proportion to compare, not a bill. API diagnostics present on 7 calls; other reasons are inferred.

when session agent reason gap rewrote premium 09-26 16:37 0f82a131 main previous_message_not_found (gap>TTL) 3h00 357k $7.05 09-26 08:50 e7185911 main previous_message_not_found (gap>TTL) 14h40 357k $7.05 09-26 09:50 ec11008d main messages_changed 12s 12k $0.23 09-26 09:13 e7185911 main messages_changed 8s 9k $0.17 09-26 10:25 ba739404 main messages_changed 2s 4k $0.09

• = reason inferred from the record (no API diagnostics on that call)

by reason n rewrote premium previous_message_not_found (gap>TTL) 2 714k $14.10 messages_changed 3 25k $0.50

by agent n rewrote premium main 5 739k $14.59

by session n rewrote premium e7185911 synthetic-squishing-platypus 2 366k $7.22 0f82a131 serialized-moseying-snowglobe 1 357k $7.05 ec11008d 1 12k $0.23 ba739404 majestic-puzzling-flask 1 4k $0.09

by model n rewrote premium claude-fable-5-1 5 739k $14.59

cachemiss  window: 24h   calls: 624   sessions: 34
prompt tokens: 152450k   cache hit rate: 97%   written: 3959k   uncached input: 12k   output: 692k
rebuilds: 10   tokens rewritten that were already cached: 986k   paid as writes: $18.08   as reads they would have cost: $0.25   rebuild premium: $17.83
Dollar figures are API list prices for the same tokens; a subscription quota is not billed in dollars, but it drains in the same proportion.
API diagnostics present on 7 calls; other reasons are inferred.

previous_message_not_found (API diagnostics): 2 rebuilds, 743k tokens rewritten, $14.67 premium, avoidable
  what it means: The API had no fingerprint of the previous request to compare against. In Claude Code this is what an expired cache entry, an aborted request or a fresh chain looks like.
  what to do:    Same as ttl_expired when it follows a long gap; otherwise the previous request carried no diagnostics.

subagent_start (inferred): 5 rebuilds, 218k tokens rewritten, $2.67 premium, expected
  what it means: A sub-agent started; it builds its own prefix from scratch, on the 5-minute cache.
  what to do:    Fewer, larger sub-agent tasks; a sub-agent that returns after five minutes idle pays the rebuild again.

messages_changed (API diagnostics): 3 rebuilds, 25k tokens rewritten, $0.50 premium, expected
  what it means: The message history differs from the previous request before the last turn: earlier messages were edited, compacted or reordered.
  what to do:    Usually compaction or a resumed session; unavoidable, but worth knowing when it happened.

cachemiss window: 24h calls: 650 sessions: 34 prompt tokens: 166521k cache hit rate: 97% written: 4187k uncached input: 12k output: 722k rebuilds: 5 tokens rewritten that were already cached: 739k paid as writes: $14.78 as reads they would have cost: $0.18 rebuild premium: $14.59 cold starts (not rebuilds): 38, of which 6 sub-agents; written: 1270k paid: $12.66 Dollar figures are API list prices for the same tokens, a proportion to compare, not a bill. API diagnostics present on 7 calls; other reasons are inferred.

previous_message_not_found (API diagnostics): 2 rebuilds, 714k tokens rewritten, $14.10 premium, avoidable what it means: The API had no fingerprint of the previous request to compare against. In Claude Code this is what an expired cache entry, an aborted request or a fresh chain looks like. what to do: Same as ttl_expired when it follows a long gap; otherwise the previous request carried no diagnostics.

messages_changed (API diagnostics): 3 rebuilds, 25k tokens rewritten, $0.50 premium, expected what it means: The message history differs from the previous request before the last turn: earlier messages were edited, compacted or reordered. what to do: Usually compaction or a resumed session; unavoidable, but worth knowing when it happened.

pip install -e ".[dev]"
pytest -q
ruff check cachemiss tests

The tests generate synthetic transcripts with known cache behaviour (a healthy loop, an expired 1-hour entry, a sub-agent on the 5-minute cache, a model switch, compaction, a growing prompt, a partial rebuild, a fork, error records, multi-block responses, a window that starts after the break) and check that every rebuild is attributed to the right reason with the right token count, before anything is claimed about real transcripts.

MIT. Written by Cedric Conday with Claude (Anthropic) as coding partner.