Prompt caching in Claude Code: why your coffee break costs more than your prompt

Every time you press Enter in Claude Code, the model rereads your whole conversation from the first line.

That sounds expensive, and it would be without prompt caching. Caching is the reason a two hour session with Claude Code stays affordable, and also the reason the first message after your lunch break can cost more than the ten before it.

Pricing and token consumption are among the new things developers using AI agents have to learn. To really understand them, you first need to understand how the caching system works. So in this post we will go through it from the ground up: what gets cached, what a cache read and a cache write cost, how the 5 minute and 1 hour TTL work, and what breaks the cache in Claude Code.

Short on time? The whole post is also a two minute video at the end.

Why does Claude reread the whole conversation every turn?

The Claude API is stateless. Anthropic’s servers keep no memory of your conversation between two messages. So each time you send something, Claude Code sends everything again: the tool definitions, the system prompt, your CLAUDE.md, every message, every file it read, every command output.

Before writing a single word of its answer, the model has to process all of those tokens. This step is called the prefill. On a 150k token session, that is 150k tokens of work on every turn, even though 99% of them are exactly the same as a minute ago.

You are probably wondering why nobody just keeps the conversation on the server. That is what prompt caching does, but only under one condition.

How prompt caching works

After processing a prompt, the server can keep the result of that work for a while. That result is the model’s internal state for those tokens (the KV cache), not the answer. On the next request, if the beginning of the prompt is byte for byte identical, the server reuses the stored work instead of redoing it.

The answer itself is never cached. The model generates the same output with or without the cache. Caching only changes how much you pay for the input and how fast the first token arrives.

The rule everything follows from is that the cache is a prefix match. The server looks for the longest start of your prompt that a previous request already stored. Change one byte at position N, and N plus everything after it misses. Everything before N still hits.

This is why order matters so much. The request is always rendered in the same order, tools, then system prompt, then messages. A change in your latest message costs nothing extra. A change in the tool list or the system prompt throws away the whole conversation behind it.

You will also meet one more word in the docs: breakpoints (cache_control in the API). The server doesn’t save the cache after every token. It only saves it at a few positions that the request marks, like the save points of a video game. The next request can only resume from a spot where a previous request saved.

In practice, Claude Code puts a breakpoint at the end of what each turn sends. When you send your next message, the request starts with exactly the same content, the server finds that save point, reads everything before it from the cache, and only processes what comes after it. You never have to place them yourself.

Why does the cache work like this?

Reusing only the beginning of the prompt isn’t an arbitrary API choice, it comes straight from the way a model like Claude reads text. Anthropic doesn’t publish how its own servers work, so what follows is how open inference engines like vLLM do it, but it explains every rule we have seen so far.

First, the model cuts your prompt into tokens, chunks of about one word. Then it reads them in order, and for each token it computes vectors, long lists of numbers that capture what this token means in this context. Context changes meaning. “Mouse” isn’t the same word in “the cat chased the mouse” and in “I clicked with the mouse”, so the vectors for “mouse” depend on the words before it. The model repeats this in every layer, the L1 to L6 rows in the video above. Real models have dozens of layers.

For the cache, two of those vectors per token matter, the key and the value, the K and the V of KV cache. Every later token uses them to “look back” at earlier tokens and pick up their meaning. That mechanism is called attention. All the keys and values of a prompt together form the KV cache. Computing them takes a full pass of the model over every token, which is the slow and expensive prefill, and prompt caching keeps them after the request instead of throwing them away. So the cache doesn’t store your text, and it isn’t a vector database either. It stores the model’s intermediate math about your text.

The important part is that a token only looks backward. The keys and values of token 500 depend on tokens 1 to 500, never on what comes after. So if token 200 changes, tokens 1 to 199 never saw it, and their keys and values are still exactly right. Every token from 200 on was computed with the old token 200, so all of them are wrong and have to be computed again. The cache can only reuse what comes before the first change. That’s the prefix match rule, and it comes straight from the math.

An old printing calculator, the kind that prints each running total on a paper roll, works the same way. Fix entry 5, and totals 1 to 4 are still right, but every total from line 5 on has to be printed again. In the figure below, each line of the roll is one token. The 4-character code on its right stands for that token’s keys and values, and like a running total, it changes as soon as that token or any token above it changes. The machine first prints request 1. The “Change token 5” button sends request 2, the same prompt with a different fifth word.

The same mechanics explain the other rules of the cache:

Cache read, cache write and the 3 token buckets

Every API response contains a usage block that splits the input of the request into three buckets. Once you know them, you can read any Claude bill.

The read multiplier depends on the model: 0.1x on most of them, 0.05x on Opus 5.5 and 0.025x on Fable 5.1. Output tokens ($20 per million on Opus 5.5) are never cached.

Two things surprise people here. First, a cache write costs more than normal input. You pay a premium to store the work, and it only pays off if a later request reads it back. Second, input_tokens is only the uncached remainder. The real size of the prompt is the sum of the three fields, so a turn that shows 300 input_tokens may still have processed 100k tokens through the cache.

5 minutes or 1 hour: how the TTL works

A cache entry doesn’t live forever. Each one has a TTL (time to live), either 5 minutes (the default, writes at 1.25x) or 1 hour (writes at 2x). Three details matter more than the TTL itself:

• A cache read resets the timer for free. If you send a message every 3 minutes, even a 5 minute entry stays warm all day.
• The timer starts when the request starts, not when it ends. If Claude spends 4 minutes on a long answer, a 5 minute entry has about 1 minute left when it finishes.
• When the entry expires, the next turn is a full miss. The whole conversation is processed again and written again, with the write premium.

Here is what a lunch break looks like with each TTL:

So which TTL does Claude Code use? It depends on how you pay, and it splits requests in two groups: the main conversation (your interactive turns, claude -p, the Agent SDK) and everything else (subagents, compaction, session titles).

The split makes sense once you think about who is waiting. A human pauses to read a diff, take a call or grab a coffee, and the 1 hour TTL covers those gaps. A subagent usually sends its next request a few seconds later, so 5 minutes is enough and cheaper. The last row is the one to remember: once you go into overage, your coffee breaks start costing full rewrites.

The subagent default has one blind spot. The timer counts from the start of one request to the start of the next, so the time a tool takes to run counts too. Three common cases go past 5 minutes without anyone noticing:

• a subagent running a test suite that takes 7 minutes,
• a subagent waiting for you to approve a permission prompt while you are away from your desk,
• a teammate in an agent team. Agent teams are several Claude Code sessions working on the same task and sending each other messages, so a teammate often waits a long time for its next message.

In all three cases the entry expires during the wait, and the next request processes and writes the whole history again.

You can override both groups (Claude Code v2.1.242 and later) with the promptCacheTtl and subagentPromptCacheTtl settings, or the CLAUDE_CODE_PROMPT_CACHE_TTL and CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL environment variables. Each one takes 5m or 1h. For subagents though, I would not switch the whole group to 1 hour: every quick exploration subagent would pay the 2x write for nothing. Set cacheTtl: 1h in the experimental frontmatter of the few agents that wait (v2.1.248 and later) and keep 5 minutes for the rest.

How much does a turn really cost?

Let’s put numbers on it. You are on Opus 5.5, your session is at 100k tokens, and the next turn adds 2k new tokens (your message, the last reply and some tool output).

A warm turn is about 11 times cheaper than no caching, and that is what makes long sessions affordable. But look at the last two rows: a cold miss costs more than having no cache at all, because you pay the write premium on the whole conversation. The bigger the session, the bigger the bill when it goes cold. That’s the coffee break from the title.

So how many requests does it take for a write to pay for itself? Here is the input cost of sending the same prefix several times, counted in full prices of that prefix (1x to process it, 1.25x or 2x to write it, 0.05x to read it on Opus 5.5):

Green is cheaper than no cache, red is more expensive. A 5 minute write pays for itself from the second request, a 1 hour write from the third. With the 0.1x read of most other models, the break-even points stay the same.

On a subscription you don’t see dollars, but the same logic applies: a long context still draws on your plan usage, even at the cached rate, so a cold miss on a big session eats into your limits faster.

Isn’t the 1 hour TTL a rip-off?

That’s the fair objection. With the 1 hour TTL, every new token you write costs 2x instead of 1.25x, on every single turn. If you work in a tight loop and send your next message within a few minutes, a 5 minute entry would have stayed warm anyway, and you paid the extra 0.75x for nothing.

For continuous traffic, that’s true. An agent loop or a script calling the API every few seconds never lets a 5 minute entry expire, so the 5 minute TTL is strictly cheaper there. It matches what Claude Code does by default: 5 minutes for subagents and for API key users.

For a human, the math goes the other way. In the 100k token session above, the 1 hour premium on a 2k token write is 2k x ($8 - $5) per million, so about $0.006 per turn. One cold miss with the 5 minute TTL costs about $0.51 instead of $0.036. You would need around 80 turns of premium to pay for a single avoided miss, and most people take more than one break in 80 turns.

What breaks the cache in Claude Code?

Now that you know the cache is a prefix match, most of this list will feel logical. Anything that changes the beginning of the prompt breaks it, anything that only adds to the end keeps it.

That last line gets its own box, because it is the least intuitive one.

/compact is worth a second look too. While the cache is warm it is cheap, because the summary is built from cached tokens. After a long break it is the expensive path: it has to read the whole cold conversation just to summarize it. If you come back after an hour and don’t need the old context anymore, /clear is much cheaper than continuing or compacting.

The flip side is that compacting early, at a natural break between two tasks, is a good habit. Every turn rereads the whole history. At 0.05x it is cheap per turn, but on a 200k token session it is still about $0.04 per turn on Opus 5.5, and everything that goes wrong (a cold miss, a model switch) costs in proportion to that size. Compacting while the cache is warm keeps all of it small. Just don’t do it in the middle of a task: the summary is lossy, and Claude may have to read again the files it just forgot.

Why I turned off the advisor tool

The advisor tool lets Claude consult a second, usually stronger model at key moments. I would not recommend it, and caching is the main reason.

Turning /advisor on keeps your cache, but the advisor itself never gets one. Each time Claude consults it, the advisor model receives the full transcript, every tool call and result included, and processes it uncached, with no reuse between calls. Even when the advisor is the same model as your main one, it doesn’t read your cache.

And you don’t choose when it happens. Claude decides, and it tends to call the advisor before declaring a task done, so at the end of a long session, when the transcript is the biggest. That’s how a single advisor call cost me a flat 700k tokens: one call at the end of a large session, with the whole context sent at full price. On Opus 5.5 prices, that is $2.80 of input for one call, where reading the same 700k from a warm cache costs $0.14.

On top of that, I haven’t seen any increase in quality while having it enabled. So I turned it off with /advisor off. If you want it gone for good, CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 disables it entirely.

How to check your own cache

You don’t have to take my word for any of this. Claude Code shows it to you.

/usage has a Prompt cache (main) line in its Session block (v2.1.251 and later) with the hit rate, the misses, whether the cache is warm or cold, and the TTL in use. Here is what it looks like in the terminal at the end of a short session:

The Prompt cache (main) line says it all: 9 requests, 94% of the input tokens read from the cache, no misses, and the cache is still warm with the 1 hour TTL of a subscription. The Opus line also lets you check the math of this post: 396.7k tokens read at $0.20 per million, 20.7k written at $8 (1 hour TTL), 526 uncached at $4 and 2.1k of output at $20 add up to the $0.2893 shown. Without the cache, the same 418k input tokens would have cost about $1.67 instead of $0.25.

Even better, your status line can show it permanently, so you know if the cache is cold before you send a message. You don’t even have to write the script: type /statusline followed by what you want, and Claude Code generates it for you.

/statusline show the prompt cache status: warm or cold, the TTL and the minutes left before it expires

The script reads the prompt_cache object Claude Code passes to your status line (v2.1.251 and later): warm, ttl, expires_at, hit_ratio, and the most useful one here, recache_tokens_if_cold, the number of tokens your next request will rewrite if the cache has gone cold. The status line also refreshes by itself when the cache reaches expires_at, so it flips to cold without you doing anything.

To see which TTL you get, run a one-shot request and look at the usage block:

claude -p "hello" --output-format json

usage.cache_creation.ephemeral_1h_input_tokens versus ephemeral_5m_input_tokens tells you which TTL was written.

What you want to see in a healthy session: cache_read grows turn after turn, because it covers everything before, and cache_creation stays small, because it is only what the last turn added. If cache_creation is close to the full conversation on every turn, something keeps changing the beginning of the prompt.

Takeaways

Prompt caching comes down to one rule: the server reuses the longest unchanged beginning of your prompt, for as long as the entry lives. Reads are almost free, writes cost more than normal input, and a cold miss on a big session costs more than having no cache at all.

In practice, that gives a few habits:

• Pick your model at the start of a session, and use subagents for cheaper models instead of switching with /model.
• After a long break, ask yourself if you still need the old context. If not, /clear instead of continuing or compacting.
• Keep big command outputs out of the conversation. They are reread on every turn, cheap per turn but it adds up, and they fill your context window.
• Watch out for overage. Once you use usage credits, the main conversation drops to the 5 minute TTL. Set promptCacheTtl to 1h if you take long breaks.
• Compact early, between two tasks and while the cache is warm, to keep the context small.
• Keep /advisor off. Every call rereads the whole conversation without any cache, and you don’t control when it happens.
• Put the cache status in your status line, so you know when your next message will be a cold one.

Here is the whole post in two minutes, to rewatch or to share. Each chapter button jumps to its part.

If you want to go deeper, the Claude Code prompt caching docs and the API prompt caching docs cover every edge case.