/cost in Claude Code: stop guessing what broke your cache

TL;DR Open /cost and find the Prompt cache (main) line. It tells you what share of your input came from cache, how many misses you have, and, since v2.1.260, what caused them. No statusline script needed to watch it by hand.

Your session starts to drag, your usage climbs, and you already know the cache is to blame. That is where the trail used to end. You had to run through the list of things that break it from memory and guess which one got you this time.

Since v2.1.251, the Session block in /cost carries one more line that closes that gap. And /cost is not a separate command: it is an alias of /usage and opens the same screen, as we covered here.

Here is what it prints on my machine, untouched:

Total cost:            $545.08
Total duration (API):  7h 41m 1s
Total duration (wall): 14d 5h 18m
Total code changes:    2322 lines added, 29 lines removed
Usage by model:
       claude-opus-5:  865.6k input, 1.4m output, 355.7m cache read, 14.8m cache write ($358.29)
      claude-fable-5:  3.8m input, 89.4k output, 0 cache read, 0 cache write ($42.72)
    claude-haiku-4-5:  374.0k input, 12.0k output, 0 cache read, 0 cache write, 3 web search ($0.4640)
    claude-fable-5-1:  4.9m input, 487.1k output, 89.7m cache read, 2.8m cache write ($143.61)
Prompt cache (main):   20 requests · 95% of input tokens from cache · no misses · warm (1h TTL, last activity 8m 39s ago)

That $545 Total cost is not a bill. On a subscription, Claude Code works it out locally at list price and nobody charges it: what each gauge actually measures.

How to read the line

Four parts, and all four cover the main conversation only. Subagents are out.

• 20 requests: the requests it has on record.
• 95% of input tokens from cache: tokens served from cache over the total input of those requests. Cache health in one number.
• no misses: nothing got reprocessed. When something does, this part becomes 2 misses (last 6m 10s ago, 310.2k tokens re-cached), with the time of the last one and what redoing it cost.
• warm (1h TTL, last activity 8m 39s ago): the cache is alive and has most of an hour left from your last move.

That third part is where the real find is. Since v2.1.260 it appends the cause by name, in the form likely cause: tool definitions changed (+3/-0). This is not a vague heuristic: it comes from a closed set of sixteen diagnoses, and the table further down is all of them.

If the cache has already expired, the fourth part turns to cold, says how long the session has sat idle, and adds how many tokens the next turn will re-cache. That figure is the full size of your last request, so read it for what it is: what you pay again the moment you type.

What counts as a miss, and what doesn't

Not every reprocess gets flagged. Claude Code counts a request as a miss when it read less than 95% of what it could have read from cache and left 2,000 tokens or more on the table. Both conditions have to hold. Below that double threshold, nothing shows up.

One case looks like a miss and isn't. When Claude Code has just rewritten the conversation itself, by compacting it or by clearing old tool results, the reprocess was unavoidable and it does not pin it on you: it lands separately as an expected rebuild. That part appears only once it has happened at least once.

The two halves of the block don't measure the same thing

Look at the example again: fourteen days on the clock, 1.4 million output tokens on Opus 5, and the cache line says 20 requests. That is not a bug, and it is worth understanding before you draw conclusions from either number.

The two halves are stored differently. Total cost, the durations, the line counts and the per-model breakdown are serialized and come back with you when you pick the session up with --resume. The cache counter lives in memory and is never written anywhere, so it starts at zero in every new process.

There is a second reason they don't reconcile. Usage by model adds up everything that ran, subagents included. Prompt cache (main) is the main conversation only, which is exactly what its name says.

/clear resets both halves together, so the gap only shows when you resume.

How to use it

1. Open the screen, don't ask for it with -p

On a subscription, claude -p "/cost" prints your plan bars and the split across skills and MCP servers, but not the Session block. That route answers a different question, which skill and which MCP are eating your limit. For this line, open /cost inside the session.

2. Read the percentage, not the cost

Prompt cache (main):   20 requests · 95% of input tokens from cache · no misses · warm (1h TTL, last activity 8m 39s ago)

Above 90% the cache is working for you and there is nothing to do. If that number slides session after session while you work the same way, something in your prefix keeps changing. For a sense of what a healthy ratio looks like, I added those counters up across three whole sessions.

3. When there are misses, read the cause instead of inferring it

This is the actual change. You used to watch two counters and work back through the suspects. Now the line hands you the name and you go straight to the fix with the table below.

Reference: the sixteen causes it can name

Those names come out of the v2.1.270 binary itself, not the docs.

If you want it in front of you all the time

This screen has to be opened. If you would rather keep the number in sight, Claude Code hands the same data to statusline scripts in a prompt_cache object, miss counts per cause included. That is where you wire it into your own status line, next to how much of your limit is gone.

This is the piece the usual trio was missing: why you pay for the whole conversation every turn explains where the spend comes from, ten habits to save tokens shrinks it, prompt caching keeps you from paying it twice, and this line tells you whether it is working. If what you want to know is when you get cut off, that is how your usage limits work.

Official docs: Prompt cache statistics

Requirements: the Prompt cache (main) line needs Claude Code v2.1.251 or later, and likely cause: needs v2.1.260. The counts come from the cache token fields the API returns on every response, so per the official docs they work on any provider and any gateway, though I have only seen it on a subscription. The likely cause: format is read from the v2.1.270 code, because my own session had no miss to show.