The model remembers nothing between requests, so on every turn Claude Code sends the whole context again: system prompt, project context, every earlier message and tool result, plus your new message. Prompt caching is what keeps that from being slow and expensive. Claude Code handles it for you, but some everyday actions break the cache and make the next turn slower and pricier.
How it works
The API caches by matching the prefix, the start of the request, against content it processed recently. On a normal turn, the prefix is the entire previous request, and only the latest exchange is new. The cached part is re-read at a much lower price instead of being processed from scratch.
The match is exact. A change anywhere in the prefix means everything after it is processed again; there is no per-file or per-segment caching. That is why Claude Code orders each request from what changes least to what changes most:
| Layer | What is in it | Changes when |
|---|---|---|
| System prompt | Core instructions, tool definitions | The set of loaded tool definitions changes |
| Project context | CLAUDE.md, auto memory, unscoped rules | A session starts, or after /clear or /compact |
| Conversation | Your messages, replies, tool results | Every turn |
A change in the conversation layer keeps the two layers above it cached. A change in the system prompt invalidates everything.
What it costs
On the Claude API, a cache read costs 0.1× the normal input price on most models, and less on the newest ones (0.05× on Opus 5.5 and Sonnet 5.5, 0.025× on Fable 5.1). Writing to the cache costs more than normal input: 1.25× for a five-minute entry, 2× for a one-hour entry. A long session that stays cached is far cheaper and faster than one that keeps missing.
How long it lives
Cache entries expire after a period of inactivity, and every request that hits the cache resets the timer. Claude Code picks the time to live (TTL) per request:
| Requests | Claude subscription, within plan usage | Usage credits, API key or cloud provider |
|---|---|---|
| Main conversation | One hour | Five minutes |
| Everything else (subagents, compaction, workflows) | Five minutes | Five minutes |
When a subscription goes over its plan limit and starts drawing on usage credits, the main conversation drops to five minutes. You can choose the TTL yourself with the promptCacheTtl setting (5m or 1h).
What breaks the cache
These make the next turn slower and more expensive, once, until the new prefix is cached:
- Switching models with
/model: each model has its own cache. - Changing effort level, on most models (on Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 with an API key or subscription, the cache is kept).
- Turning on fast mode (once per conversation).
- Connecting or removing an MCP server, when its tools are loaded upfront rather than deferred.
- Enabling or disabling a plugin that provides MCP servers.
- Denying an entire tool, when tool search is off.
- Compacting (
/compactor auto-compaction): the history is rewritten into a summary. - Accumulating many images: old ones get dropped, which changes earlier messages.
- Upgrading Claude Code: the first session after an upgrade builds its cache from scratch.
- A long pause longer than the TTL.
What keeps it
- Editing files in your repo (Claude Code appends a “file changed” note instead of rewriting history).
- Changing permission mode or output style.
- Invoking skills and commands.
/rewind, which goes back to a prefix that is already cached.- Spawning a subagent: it builds its own cache and leaves yours alone.
Editing CLAUDE.md mid-session keeps the cache too, but for an unexpected reason: the edit does not apply. Claude keeps the version loaded at session start until the next /clear, /compact or restart.
How to check it
Run /usage. On recent versions (v2.1.251 or later), the Session block has a Prompt cache (main) line with the hit ratio, the miss count, whether the cache is warm right now and, when Claude Code can tell, the likely cause of the last miss. A status line script can show the same numbers from the prompt_cache object.
What to do about it
- Pick the model and effort level at the start of a session, not mid-task.
- Run
/compactand/clearat natural breaks between tasks, not in the middle of one. - If you went down the wrong path,
/rewindinstead of compacting: it reuses the cache.
Related
- Context window: what is being re-sent on every turn.
- Managing context: habits that keep both the context and the cache healthy.
- Statusline: watch cache and context numbers live.