This post used to say Claude Code's prompt cache expires after five minutes, so a coffee break costs you a rebuild. That is the Anthropic API default, and it is wrong for Claude Code. Measured across 63,880 billed API requests, 100% of Claude Code's cache writes are on the 1-hour tier and none on the 5-minute tier, which also means every write bills at 2x base input rather than 1.25x. Seven places in this post carried the wrong version, two of them inside the FAQ structured data where a body edit would not have reached them, and one of them a cost claim that did not mention a lifetime at all and so survived the first sweep. All seven are now fixed. The measurement is in what a long CLAUDE.md actually costs.
Why Anthropic Treats Cache Misses Like Outages
The Claude Code team monitors prompt cache hit rate like infrastructure uptime. If it drops too low, they open an incident. Not a bug ticket - an incident.
That surprised me. But once I understood why, a dozen confusing Claude Code behaviors clicked into place. Why CLAUDE.md loads before your conversation. Why plan mode is a tool call. Why /clear feels expensive. Every single one traces back to one constraint: prompt caching.
Anthropic's prompt caching documentation explains the API-level mechanics. This post goes deeper - into how those mechanics shape the tool you use every day.
How Prompt Caching Actually Works
Prompt caching works by prefix matching. Claude can cache a prefix of the conversation and reuse it on the next request - but only if that prefix is byte-for-byte identical. Change one character early in the prompt and the entire cache after that point is invalidated.
That one rule drives every UX decision in Claude Code.
Prefix Matching in Practice
If static content sits at the front of the prompt and dynamic content sits at the back, the static part stays cached across requests. If you flip that order - dynamic first, static after - you rebuild the cache on every message.
Same tokens. Wildly different cost.
A cache entry has a lifetime, and the lifetime sets the write price. The API default is a 5-minute TTL (time to live) at 1.25x the base input rate; a 1-hour TTL is available at 2x.
Claude Code does not use the API default. Measured across 63,880 billed API requests on 2026-08-30, every single cache write was on the 1-hour tier and the 5-minute tier was exactly zero. So inside Claude Code a coffee break does not cost you a rebuild, and every write bills at 2x rather than 1.25x. The full measurement is in what a long CLAUDE.md actually costs.
Since Claude Code 2.1.243 the lifetime is configurable through the promptCacheTtl and subagentPromptCacheTtl settings, so the 1-hour tier is a measured default rather than a property of the tool. If you set promptCacheTtl to five minutes, the five-minute behaviour below applies to you again.
The Numbers That Matter
| Metric | Value | Source |
|---|---|---|
| Cache write cost | 25% more than base input tokens on the 5-minute TTL, 100% more on the 1-hour TTL | Anthropic docs |
| Cache read cost | 90% discount vs uncached input | Anthropic docs |
| Cache TTL | 5 minutes by default, 1 hour available | Anthropic docs |
| Minimum cacheable prefix | Varies by model, see below | Anthropic docs |
The minimum cacheable prefix is per-model, and you cannot infer it from how new or how capable the model is. It falls steadily across the Opus line, and then the same-generation pair breaks any rule you might draw from that: Sonnet 4.5 sits at 1,024 and Haiku 4.5 at 4,096, four times apart. Look it up per model rather than reasoning about it. Below the minimum, nothing caches and you get no error: cache_creation_input_tokens simply comes back as 0. Verified against Anthropic's documentation on 2026-08-15:
| Model | Minimum prefix |
|---|---|
| Opus 5, Fable 5 | 512 tokens |
| Opus 4.8, Sonnet 5, Sonnet 4.6, Sonnet 4.5 | 1,024 tokens |
| Opus 4.7 | 2,048 tokens |
| Opus 4.6, Opus 4.5, Haiku 4.5 | 4,096 tokens |
Haiku 4.5 is the trap: at 4,096 it needs an eight times longer prefix than Opus 5 does, and four times what its own generation-mate Sonnet 4.5 needs. A 3K-token prompt caches on Opus 5 and Sonnet 5 and silently will not cache on Haiku 4.5 - which is exactly the model you reached for to save money.
At a 90% discount on cached reads, the difference between a cached and uncached session is dramatic. A 100K-token context with 80% cache hit rate costs roughly 8x less per request than the same context with 0% hits.
The Prompt Assembly Order
Claude Code assembles your prompt in a very specific order. This is not arbitrary - it is deliberately structured so the most stable content sits earliest in the prefix.
Layer 1: System Prompt and Tools
The system prompt and all tool definitions sit at the very front. These are identical across requests within a session, so they cache on the first message and stay cached. This is why MCP tool search defers tool schemas instead of loading them all up front. Deferred tools are known by name only until something actually needs one, and the full schema arrives later in the conversation rather than being edited into the front of it. The prefix stays byte-identical, so the cache survives.
Layer 2: CLAUDE.md and Static Context
Your CLAUDE.md file, rules files, and any static project context load next. These are more stable than your conversation but less stable than the system prompt (they can vary across projects). This layer caches after the first turn and stays cached for the session.
This is why changes to CLAUDE.md do not take effect mid-session without a restart - the file loaded at session start is baked into the cached prefix.
Layer 3: Conversation Messages
Your actual messages sit at the back. They change every turn, so they are never cached as input (though they become part of the prefix for the next request). This is the dynamic layer where caching ends and full-price token processing begins.
Now watch what happens when something changes at layer two - a tool gets added, a model switches, or the system prompt gets edited. Everything below that point rebuilds from scratch.
That cascade is the cost nobody sees. One change at the wrong layer, and thousands of cached tokens become full-price tokens on every subsequent request.
What Breaks the Cache
Understanding what invalidates the cache is more useful than understanding what preserves it. Here are the four most common cache breakers:
1. Switching Models Mid-Session
Each model has its own cache. When you switch from Opus to Haiku mid-session, the Haiku model has no cached prefix - it builds from scratch at full token prices.
At high context volumes, this is counterintuitive: the full-price Haiku cost can exceed what Opus would charge at cached rates.
# What you think happens
Opus (expensive) → Haiku (cheap) = savings
# What actually happens at 100K cached context
Opus @ cached rate: ~$0.30/request
Haiku @ uncached rate: ~$0.25/request (first), then cached
# Plus you pay the cache write cost again
The Anthropic team confirmed this directly. Choose your model at session start and stay with it.
2. Adding or Removing Tools
Tools are part of the prefix. Adding a tool partway through invalidates everything cached after that point. This is why ToolSearch exists as an architecture pattern - deferred tool loading that keeps the prefix stable.
3. Using /clear Instead of Compaction
/clear destroys the session and forces a full cache rebuild. Compaction uses what the team calls "cache-safe forking" - same system prompt, same tools, same prefix, with a summary appended at the end. The cached prefix survives.
4. Long Pauses Between Messages
This one is the opposite of what I originally wrote here, and it is worth being precise about who it applies to.
Inside Claude Code, a coffee break does not cost you a rebuild. Claude Code runs on the 1-hour tier by default, measured at 100% of cache writes with the 5-minute tier at zero, so a gap of minutes leaves the cached prefix intact. Long thinking pauses are not a cost problem there.
If you are calling the API yourself, the 5-minute default does apply, and a pause longer than that rebuilds the prefix on your next request. The 1-hour TTL survives the gap at double the write cost, so it pays off once enough reads follow, which for any real session is quickly.
Six Things This Changes About Your Workflow
The caching architecture has direct implications for how you should work:
CLAUDE.md loads before your conversation. Not because it is special - because it is more static than your messages. It gets cached after the first turn and stays cached for the session.
The <system-reminder> tags in your transcript are not noise. When Claude Code needs to inject updated instructions, it appends them to messages instead of modifying the system prompt. Modifying the system prompt would break the cached prefix. Those tags are saving cache hits on every subsequent request.
Plan mode is a tool call, not a mode swap. EnterPlanMode and ExitPlanMode appear as tool calls. If plan mode were a separate system prompt state, switching in and out would invalidate the cache. As a tool, it leaves the prefix intact.
Never add or remove tools mid-session. Tools are part of the prefix. Adding one partway through invalidates everything cached after that point. Plan your tool set upfront.
Model switching costs more than you think. At 100K tokens of cached context, switching from Opus to Haiku does not save money - it rebuilds the cache from zero. Choose at session start.
Long sessions benefit from cache stability. A 2-hour focused session with a warm cache is dramatically cheaper per-request than 12 short sessions that each rebuild from zero.
Cache-Safe Compaction vs /clear
This deserves its own section because the wrong choice here is the most expensive daily mistake.
- -Cache rebuilt from zero each time
- -Full token cost on every request
- -Session history gone
- -Faster perceived start, slower actual performance
- +Cached prefix preserved
- +Cache hit rates stay high
- +Summary bridges old and new context
- +Consistent cost across the session
I used to /clear after every task. Now I only use it when I genuinely need a fresh context, not just a clean conversation view.
When to Actually Use /clear
- Starting a completely unrelated task (different project, different domain)
- The session has accumulated too much irrelevant context that compaction can't shrink
- You suspect the model is stuck in a behavior loop and need a true reset
For everything else, let compaction handle it. The session management patterns I use are built around this principle.
How to Audit Your Own Cache Behavior
If your Claude Code sessions feel inconsistent - sharp early, degraded later - check whether you are accidentally breaking the cached prefix.
Symptoms of Cache Degradation
- Sessions that suddenly feel slower after a model switch or tool change
- Unexpectedly high token usage reported in the billing dashboard
- On the API with the 5-minute default, a slow first response after a gap longer than the TTL (not a Claude Code symptom: it runs on the 1-hour tier)
Quick Self-Check
- Are you switching models mid-session? Stop. Pick one at the start.
- Are you using /clear between tasks? Switch to compaction.
- Are you adding tools mid-session? Plan your tool set upfront in your CLAUDE.md configuration.
- Are you calling the API directly with the default TTL? Then a break longer than five minutes rebuilds the prefix. In Claude Code it does not, so breaks are not the thing to change.
If your Claude Code sessions feel inconsistent - sharp early, degraded later - check whether you are adding tools, switching models, or using /clear mid-session. Any of those breaks the cached prefix and forces a rebuild.
Why This Architecture Exists
Prompt caching is not a nice-to-have. At the token volumes Claude Code sessions generate - especially with long CLAUDE.md files, large tool sets, and extended conversations - without caching the cost would make the tool impractical for daily use.
The architecture is a product constraint turned into a design principle. And once you see it, the entire tool becomes more legible:
- The context management system I built is partly a cache optimization strategy in disguise - keeping stable content stable and dynamic content minimal.
- The delegation system benefits too - sub-agents start with a small, focused prefix instead of inheriting a bloated 100K-token conversation. Less prefix, less cost, regardless of cache state.
- Hooks preserve the prefix by design - they inject behavior through tool-use events, not system prompt modifications.
Every pattern I use connects back here.
This lives in primeline-ai/evolving-lite - the self-evolving Claude Code plugin. Free, MIT, no build step.
