The 20x in Claude Code caching is real — it's a penalty, not a discount

There is a whole genre of advice going around right now: stop burning your Claude limits. It shows up as videos, threads and posts, and it converges on the same handful of claims — that a mishandled cache costs you half your weekly allowance, that one environment variable fixes it, that stepping away from the keyboard doubles your bill, and that the payoff is a 20x reduction in spend.

Most of the mechanics in that advice are correct. Anthropic documents them, and the better versions of the advice clearly read those docs. What the genre gets wrong is the arithmetic wrapped around the mechanics — which is the part that decides whether you should change anything.

So we checked every claim against Anthropic’s own documentation, then did the math on our own pricing snapshot. Three things came out of it. The 20x is real and it is the opposite of a discount. The one setting everyone tells you to change does nothing for most of the people being told to change it. And the headline number — the share of your weekly limit at stake — is not computable by anyone outside Anthropic, including us.

The 20x is real, and it is a penalty

Prompt caching has three prices, all of them fixed multipliers of a model’s base input rate. Anthropic states them plainly: five-minute cache writes cost 1.25x the base input price, one-hour cache writes cost 2x, and cache reads cost 0.1x.

Divide the one-hour write by the read and you get exactly 20. That is where the 20x comes from.

It is worth being precise about what the number describes, because the framing does all the work here. It is not “caching makes your spend 20x smaller.” It is: re-writing a block of history costs twenty times what reading the same block from a warm cache costs. You do not earn 20x by caching well. You pay 20x by caching badly.

Because these are multipliers rather than independent prices, the ratio is identical across Anthropic’s entire current lineup — and it survives any repricing, since only the dollar column moves:

Per million tokens. Rates from our snapshot, each verified on Anthropic’s pricing page; miss penalty is the one-hour write rate divided by the cache read rate. On the five-minute TTL the same penalty is 12.5x.

The 20x applies to the history block only, so a whole turn never quite reaches it — your new message and your output tokens are not cacheable and dilute the ratio. Here is one Opus 5 turn, warm versus cold, as the conversation grows. Assume 6,000 new tokens appended and 1,500 output tokens, which is a modest agentic turn:

The shape of that table is the actionable part. A cache miss early in a session is a rounding error. The same miss six hours in, on a session carrying 600k tokens, costs $5.70 — and the deeper you are, the closer the penalty creeps toward the full 20x. The cost of a cache miss is a function of how long you have been talking, not of what you asked.

The timer runs while Claude is thinking

This is the single most useful mechanical fact in the whole topic, and it is easy to get backwards. Anthropic’s caching documentation states it directly: the cache lifetime “is measured from the start of the request that writes or reads the cache entry, not from the end of its response,” and “time spent generating a response counts against the lifetime.” The docs give the worked case: a response that takes four minutes to stream leaves roughly one minute for a follow-up before a five-minute window closes.

Think about what that does to the most-recommended way of working with an agent. Hand it a large, well-specified task, walk away, come back later. Now the model spends twenty minutes reasoning and running tools — and every one of those minutes is spent out of the window you needed to be inside. On the five-minute TTL, a long autonomous run is guaranteed to end with a cold cache, regardless of how quickly you type your next message.

The one-hour TTL exists precisely for this, and it is why Claude Code requests it by default on subscriptions. But the general principle holds at any TTL: the clock you are racing includes the model’s own working time, not just yours. Sessions that consist of many fast exchanges keep a cache warm essentially for free. Sessions built from a few very long autonomous runs pay a re-write at the start of every one.

That is not an argument against long autonomous tasks — for many jobs they are the right shape, and the re-write is a fair price for not sitting at the keyboard. It is an argument against believing you are getting cache economics you are not getting.

The setting everyone tells you to change

The most-repeated piece of actionable advice in this genre is: set ENABLE_PROMPT_CACHING_1H=1, it works on subscriptions and on API keys alike, it takes ten seconds, everyone should do it.

The variable is real. The advice is close to backwards for the audience it is aimed at.

Anthropic’s Claude Code documentation is unambiguous about the defaults. “On a Claude subscription, Claude Code requests the one-hour TTL automatically, so the cache survives breaks of up to an hour.” If you are on Pro or Max and inside your plan limits, you already have the setting the advice is telling you to enable. Setting it changes nothing.

There is exactly one situation on a subscription where it does something, and the docs spell that out too. Once you exceed your plan’s usage limit and Claude Code starts drawing on usage credits, you are billed per token — so Claude Code automatically drops you to the five-minute TTL, because one-hour writes cost more. The environment variable overrides that protection. In other words, in the only case where the flag has any effect on a subscription, its effect is to opt you back into more expensive cache writes than Claude Code chose for you.

Whether that is right depends entirely on your gaps, and the break-even is easy to state. One-hour writes cost 2x base input; five-minute writes cost 1.25x. On a 200k-token history block on Opus 5, that is $2.00 versus $1.25:

The one-hour TTL pays for itself on the first gap. Formally the break-even is 0.6 of a re-write, so a single miss more than covers it. If you genuinely never pause for six minutes — including the model’s own thinking time — the shorter TTL is 60% cheaper on writes. Nobody working with an agent all day is in that situation.

For API keys, Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry and Claude Platform on AWS, the default is five minutes and the flag is straightforwardly useful. In a modelled 30-turn Opus 5 session with a six-minute gap every fifth turn, the one-hour TTL came out at $4.84 against $8.35 — 42% cheaper. That is the real version of the advice, aimed at the people it actually applies to.

Since Claude Code v2.1.242 the TTL is no longer one dial but two. Claude Code sorts every request into one of two buckets — the main conversation (your interactive turns, -p runs, Agent SDK turns) and everything else (subagents, workflows, in-process teammates, forks, compaction, session titles) — and each bucket has its own control: promptCacheTtl or CLAUDE_CODE_PROMPT_CACHE_TTL for the first, subagentPromptCacheTtl or CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL for the second. Both take 5m or 1h and ignore anything else. FORCE_PROMPT_CACHING_5M=1 still overrides both, which is what you want for debugging cache behavior or for overriding an ENABLE_PROMPT_CACHING_1H that arrived through managed settings; ENABLE_PROMPT_CACHING_1H now sits near the bottom of the precedence order, below both per-bucket controls.

What breaks the cache — including two nobody mentions

Prompt caching is a prefix match. Anthropic’s Claude Code team put it as bluntly as it can be put: “Any change anywhere in the prefix invalidates everything after it.” Claude Code orders each request so the stable content comes first — system prompt and tool definitions, then project context, then the conversation — so a normal turn changes only the tail and leaves everything before it cached.

The documented invalidators are these:

• Switching models. Each model has its own cache. /model mid-conversation re-reads everything.
• Changing effort level. Effort is part of the cache key alongside the model. Set it at the top of a session.
• Turning on fast mode. The header is part of the cache key. This costs the cache once per conversation — after the first fast-mode turn, toggling it off and on again keeps the cache, because only the speed setting varies and that is not part of the key. Turning it on early in a session therefore costs much less than turning it on deep into a long one. Note that fast mode is Opus 5 and Opus 4.8 only, and its uncached input is billed at fast-mode rates of $10/$50 per million.
• Connecting or disconnecting an MCP server — but only when its tools load into the prefix. On supported models tools are deferred by default, so a server connecting or changing its tool list only appends. When tools are not deferred, this is the invalidator most likely to fire without you doing anything: a stdio server’s process exits, an HTTP session expires, a server reconnects after a transient failure. We covered the deferral mechanism in the MCP context tax.
• Enabling or disabling a plugin — only if it provides MCP servers whose tools load into the prefix. Skills, commands, agents, hooks, monitors and themes never invalidate; they append.
• Denying an entire tool. A bare deny rule like Bash removes a built-in tool definition from the system prompt layer. Scoped rules such as Bash(rm *) and all allow and ask rules leave the prefix intact.
• Compacting. By design — see below.
• Upgrading Claude Code. A new version usually changes the system prompt or tool definitions.

Two invalidators are missing from essentially every version of this advice, and both are things you do without realising they are model switches.

The first is the opusplan setting. It resolves to Opus during plan mode and Sonnet during execution — so every toggle in and out of plan mode is a model switch that starts a fresh cache. The usual objection to plan-with-Opus-execute-with-Sonnet is a quality argument about handoffs. The cache argument is sharper and entirely mechanical, and it applies even if you love the quality.

The second is automatic model fallback. On Fable 5 and Opus 5, when a safety classifier flags a request and the flagged category has a fallback model, Claude Code re-runs the request on that model and the session continues there. That is a model switch you did not ask for and did not notice.

And one more that is documented but rarely mentioned: resuming a session after an upgrade reprocesses the entire history with no cache hits, because the history now sits behind a different system prompt. Anthropic’s note on it is worth quoting in spirit — the cost scales with how long the resumed conversation is, so the first turn back into a long session can be the most expensive request you send.

What keeps the cache — including the escape hatch

The other half of the list matters just as much, because several things that feel expensive are free:

• Editing files in your repo. File contents enter context only when Claude reads them; a later edit appends a note rather than rewriting history.
• Editing CLAUDE.md mid-session. It does not invalidate the cache — and it also does not apply. Claude keeps working from the version loaded at session start. The new content loads on the next /clear, /compact or restart.
• Changing output style. Same deal: no invalidation, and no effect until restart.
• Changing permission mode — except plan mode under opusplan, per above.
• Invoking skills and commands. They inject instructions as user messages at the point of invocation.
• /recap, which appends a summary as command output rather than replacing history.
• Spawning a subagent, from the parent’s point of view.

The one that deserves promotion to a habit is /rewind. It truncates the conversation back to an earlier turn, and because the remaining history is exactly the content the cache was built from, the next request hits the earlier cache entry. Anthropic adds a detail that makes this better than it sounds: every turn since then read through that prefix, which kept the entry warm even if the original turn was longer ago than the TTL.

So when you realise you have gone down a wrong path, rewinding is not just cheaper than compacting — it is nearly free, while compaction builds a new prefix from scratch.

Compaction, clearing, and which one is actually cheap

/compact has a reputation for being expensive that is half-earned. To produce the summary, Claude Code sends a separate request carrying the same system prompt, tools and history as your conversation plus a summarization instruction. While the cache is warm, that request reads your prefix from the cache — so a mid-session compaction costs a fraction of what the context size suggests, and spends most of its time generating the summary. Cold, after a break longer than the TTL, there is no cache to read and the whole history is reprocessed as uncached input.

That is the real rule, and it is a timing rule rather than a cost rule: compact while warm, at a natural break between tasks, rather than letting auto-compaction fire mid-task. We went deeper into the mechanics and the billing pass you do not see in compaction: when to summarize an agent’s history, and into the API-level alternative in context editing.

/clear, by contrast, costs nothing. Anthropic’s cost documentation says so in those words. When you want a fresh start rather than continuity, clearing is strictly the cheaper move — and it is the single most effective thing in this entire article, for reasons the next section makes arithmetic.

Subagents run on a different clock

A subagent starts its own conversation with its own system prompt and tool set. Its first request cannot read the parent’s cache because the prefixes differ, and it warms a cache of its own across its turns. The parent is unaffected — the subagent’s call and result simply append.

The detail worth internalising: subagents get five minutes by default even on a subscription, because the automatic one-hour TTL covers the main conversation only. A subagent that thinks for four minutes and then needs a follow-up is in exactly the squeeze described earlier. Setting subagentPromptCacheTtl to 1h moves that whole bucket to the hour — at the higher write rate, so it is the same trade as everywhere else. We priced that trade for fan-outs in what it costs to run many agents at once.

A fork is the opposite case. It inherits the parent’s system prompt, tools and conversation history exactly, so its first request reads the parent’s cache. If you are choosing between spawning a subagent and forking, and the work needs the parent’s context anyway, the fork starts warm.

Agent teams are the extreme version of this, and worth a number: Anthropic’s docs put them at roughly 7x the tokens of a standard session when teammates run in plan mode, because each teammate maintains its own context window as a separate Claude instance.

Cache scope is machine plus directory

Claude Code’s cache is, in Anthropic’s phrasing, “effectively scoped to one machine and directory.” The system prompt embeds the working directory, platform, shell, OS version and auto-memory paths, so two sessions in different directories build different prefixes and cannot read each other’s cache. That explicitly includes separate worktrees of the same repository.

Two consequences people get wrong in both directions:

• Sessions running in parallel in the same directory share a cache. Their prefixes match, so they read each other’s entries. Running two Claude Code windows on one repo is not doubling your cache cost.
• Branches matter only across sessions, not within one. The system prompt also captures branch and recent commits — but it captures them in a snapshot taken at startup. So sequential sessions share a prefix only when that snapshot matches, while switching branches mid-session invalidates nothing.

The underlying API cache is broader than the Claude Code view of it: caches are isolated between organizations, and on the Claude API, Claude Platform on AWS and Microsoft Foundry also between workspaces within an organization; Bedrock and Google Cloud use organization-level isolation only.

What caching cannot fix

Here is the part the genre skips, and it is the part that decides how much any of this is worth.

Caching does not stop you paying for your history. It discounts it — on every single turn, for as long as the session lives. A cache read is 0.1x base input, not zero. Claude Code re-sends the entire conversation with every request, so a one-line question in a session that has been open all day still draws usage for the whole conversation. Anthropic’s own cost docs list exactly that under the reasons usage climbs in a long session.

Put numbers on it. On Opus 5, the history block alone, before Claude does any work at all:

At a perfect 100% hit rate, a 600k-token session costs 30 cents a turn just to re-read what you already said. Twenty turns is six dollars of pure history. No TTL setting touches that. /clear eliminates it outright, and costs nothing.

Now the full session. Modelling thirty turns on Opus 5 — 25,000 tokens of system prompt, project context and tool definitions at the start, 6,000 tokens appended per turn, 1,500 output tokens per turn, finishing at roughly 205k of context:

Three cold turns out of thirty added 82% to the session. Systematic thrashing more than tripled it. That is the strongest case for the advice genre, and we should say so plainly: on the mechanics, it is right that this matters a great deal.

But look at the output column, because it inverts in a way that is easy to misread. Output is a fixed $1.12 in all three rows — caching never touches it. It looks like a shrinking share (23% to 7%) only because input is exploding. The worse your caching, the smaller output appears, and the more tempting it becomes to conclude output does not matter. In the well-cached session, output is nearly a quarter of the bill, thinking tokens included — and effort level is the lever there, which we worked through in reasoning effort and what it actually costs. Output-side tools like caveman mode land in the same place: real, and bounded by output’s share of the bill.

This also fixes the most-repeated bad reason in the genre. Anthropic’s docs do say to keep CLAUDE.md under 200 lines — that number is correct and it is Anthropic’s. The reason usually attached to it, that Claude Code recomputes the file from scratch every turn, is wrong. CLAUDE.md sits in the cached project-context layer, is read once at session start, and gets re-read only on /clear, /compact or restart. The real cost is occupancy: those tokens ride along on every unrelated request for the entire session, and they are re-written at the write rate every time the prefix rebuilds. That is a strong argument for moving workflow-specific instructions into skills, which load on demand — and a much better argument than the false one.

The number nobody can compute

Which brings us to the headline that started all of this: mishandling your cache costs up to half your weekly limits.

We cannot verify that. Neither can anyone else outside Anthropic, and the reason is structural rather than a gap in the research.

Anthropic publishes per-token prices for the API in full: input, output, cache reads, both cache write tiers, batch. What it does not publish is the conversion between tokens and subscription plan limits. The support documentation describes usage as a budget affected by “the length and complexity of your conversations, the features you use, which Claude model you’re chatting with, and the effort level you’ve selected.” That is a list of inputs, not a formula. There is no published rate at which a cached token, an uncached token, or an output token consumes your five-hour or weekly window.

What is established, from three independent primary sources, is the direction:

1. Anthropic’s Claude Code cost documentation lists cache misses among the reasons usage climbs in a long session, and describes history being re-read “at the cached token rate.”
2. The /usage plan breakdown flags cache misses as a behavior when they account for 10% or more of your recent usage — Anthropic would not surface a flag for something that did not move the meter.
3. Anthropic’s engineering blog on building Claude Code states that a high prompt cache hit rate “decreases costs and helps us create more generous rate limits for our subscription plans,” and that they alert on the hit rate and declare incidents when it drops.

So: cache hits stretch your plan limits. That is settled. The magnitude is not, and every specific percentage in circulation — half your weekly limit, 20% on Max 5x, 20x less spend — is an extrapolation from API dollar prices onto a meter whose formula the vendor does not publish. Ours would be too, which is why we have not given you one.

What you can do instead is measure your own. Two token counts come back on every response: cache_read_input_tokens and cache_creation_input_tokens. A high read-to-creation ratio means caching is working; creation staying high turn after turn means something in your prefix keeps changing, and the invalidator list above is where to look. Surface them in a statusline and you have a live cache gauge. On a paid plan, /usage adds attribution across skills, subagents, plugins and individual MCP servers, with a day and week toggle — and /insights writes a deeper report, at the cost of tokens that count against your own plan.

The checklist that survives repricing

Everything below is a consequence of fixed multipliers or documented mechanics, not of today’s prices — so none of it goes stale when Anthropic reprices.

1. Pick your model and effort at the top of a session. Both are part of the cache key. Mid-task changes cost a full re-read.
2. Avoid opusplan if you toggle plan mode often. Every toggle is a model switch.
3. Turn fast mode on early or not at all. It costs the cache once per conversation, and that cost scales with how deep you are.
4. Rewind instead of compacting when abandoning a path. Rewind lands on a prefix that is already warm.
5. Compact at task boundaries while warm, never on a resumed cold session if you can help it.
6. Clear between unrelated tasks. It costs nothing and it is the only thing that removes the per-turn history charge entirely.
7. Keep CLAUDE.md lean and move workflows into skills — for occupancy, not for recomputation.
8. Prefer CLI tools over MCP servers where both exist, and let tool search defer what stays.
9. Reach for a TTL control only if you pay per token — API key, cloud provider, or a subscription drawing on usage credits — and only if your gaps regularly exceed five minutes. Prefer the per-bucket settings (promptCacheTtl, subagentPromptCacheTtl) over the blanket ENABLE_PROMPT_CACHING_1H.
10. Watch the two cache counters, not the advice.

If you want to put your own numbers against the ratios in this piece, the LLM API calculator models cache hit rates against the same verified snapshot these tables come from, and how to actually get prompt cache hits covers the API-side breakpoint rules that sit underneath everything Claude Code does automatically. For the tool itself — what it costs on each plan and how the access routes compare — see our Claude Code pricing breakdown and how to check Claude Code usage.

Sources: Anthropic’s prompt caching documentation, how Claude Code uses prompt caching, managing Claude Code costs, usage and length limits, and Lessons from building Claude Code: prompt caching is everything. All rates from our own snapshot, each verified on Anthropic’s pricing page; see methodology. Checked 23 August 2026.