Claude Code prompt caching: what breaks the cache and how to check it

Claude Code prompt caching is automatic: every turn re-sends your whole conversation, and the API reuses the unchanged start of that request from cache instead of reprocessing it, which makes turns faster and cheaper. Some actions, like switching models or connecting an MCP server, change that start and force one slow, uncached turn.

You do not need to configure anything to get caching. Knowing what breaks it helps you avoid paying for the same context twice. This guide summarizes Anthropic's prompt caching page for Claude Code, checked on 24 October 2026.

How does prompt caching work in Claude Code?

The model does not remember anything between requests. Each time you send a message, Claude Code sends the system prompt, your project context, every earlier message and tool result, and your new message. Most of that is identical to the previous request.

The API caches by matching the start of each request, the prefix, against content it processed recently. The docs are clear that "The match is exact, so a change anywhere in the prefix recomputes everything after it. There is no per-file or per-segment caching."

To keep the prefix stable, Claude Code orders each request so that content that rarely changes comes first:

A change to the conversation leaves the layers above it cached. A change to the system prompt invalidates everything below it. Two more things act as part of the cache key even though they are not in the table: the model, and on most models the effort level.

How much does prompt caching save?

Cached reads cost a fraction of normal input. Per the Claude API prompt caching docs, read October 2026:

That gap is why a cache miss on a long conversation is noticeable. On a subscription it eats into your usage limits faster; with an API key it shows on the bill. See the Claude Code cost guide for how usage is reported.

Which actions invalidate the Claude Code cache?

Each of these makes the next request miss part or all of the cache. You see one slower, more expensive turn, then the new prefix is cached:

• Switching models. Each model has its own cache. Claude Code asks you to confirm a /model switch while the cache is warm. The opusplan setting switches between Opus and Sonnet as you enter and leave plan mode, so each toggle starts a fresh cache.
• Changing effort level. On most models this reprocesses the whole conversation. On Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 with an API key or Claude subscription, the cache stays intact by default.
• Turning on fast mode. It adds a request header that is part of the cache key. The cost applies once per conversation, so turning it on early is cheaper than deep into a long session.
• Connecting or removing an MCP server. Tool definitions sit in the system prompt. With tool search on, the default on supported models, mid-session server changes do not disturb the cache. Without it, adding tools invalidates it.
• Enabling a plugin that provides MCP servers. A plugin's skills, commands, agents, hooks and themes never invalidate the cache; its MCP servers follow the MCP rules above.
• Denying an entire tool. A bare deny rule like WebFetch removes the tool definition when tool search is off. Scoped rules like Bash(rm *) never change the prefix.
• Compacting. /compact replaces history with a summary by design.
• Accumulating many images. When a request would pass the image limits, Claude Code drops a batch of the oldest images, which changes earlier messages.
• Upgrading Claude Code. A new version usually changes the system prompt, so the first conversation after an upgrade builds its cache from the top.

Which actions keep the cache?

These append to the conversation or do not touch the request at all:

• Editing files in your repo. Claude Code appends a note that the file changed rather than rewriting the earlier read.
• Editing CLAUDE.md mid-session. The cache stays, but so does the old content: the docs say "Claude keeps working with the version that was loaded at session start" until /clear, /compact or a restart.
• Changing permission mode, except plan mode under opusplan.
• Changing output style. The new style arrives as a message.
• Invoking skills and commands, unless their frontmatter names a different model.
• Running /recap, which appends a summary instead of replacing history.
• Using /rewind, which truncates back to a prefix that is already cached.
• Spawning a subagent. It builds its own cache; the parent's prefix is untouched.

How long does the cache last?

Cached prefixes expire after a period of inactivity, and every cache hit resets the timer. The API offers a five-minute TTL and a one-hour TTL that costs more to write. Claude Code picks one per request:

Once a subscriber goes over the plan limit and starts drawing on usage credits, the main conversation drops to five minutes, since that charges less per write.

You can choose the TTL yourself with 5m or 1h. For the main conversation, use the promptCacheTtl setting or CLAUDE_CODE_PROMPT_CACHE_TTL. For everything else, use subagentPromptCacheTtl or CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL. Both need Claude Code v2.1.242 or later. With an API key or a cloud provider, this is how you give the main conversation a one-hour cache:

{
  "promptCacheTtl": "1h"
}

The longer TTL pays off when you leave a session idle and come back. It costs more on short bursts of work that never go idle past five minutes. To confirm which TTL your writes used, run claude -p "hello" --output-format json and look at usage.cache_creation: one-hour writes show under ephemeral_1h_input_tokens and five-minute writes under ephemeral_5m_input_tokens.

How do you check your cache hit rate?

The quickest check is /usage. On v2.1.251 or later, its Session block includes a Prompt cache (main) line with the hit ratio, miss count and whether the cache is warm right now. On v2.1.260 or later, it also names the likely cause of the last miss, such as likely cause: tool definitions changed.

For a live view, a status line script can read two per-turn fields:

A high read-to-creation ratio means caching is working. If creation stays high turn after turn, something keeps changing your prefix. For teams, the OpenTelemetry exporter reports cache tokens per user and session; see the monitoring docs.

Does caching work with Bedrock, Vertex and gateways?

On Amazon Bedrock and Google Cloud's Agent Platform, the cache lives in the cloud provider's infrastructure. On Bedrock, support, minimum prefix length and one-hour availability vary by model. Behind an LLM gateway or a custom ANTHROPIC_BASE_URL, caching depends on how the gateway treats the cache_control markers Claude Code sends. If it strips them while returning success, "your entire conversation history bills as uncached input on every turn." For a one-hour TTL through a gateway, it must forward the anthropic-beta header unchanged. The Bedrock and Vertex guide and LLM gateway guide cover setup.

What habits keep the cache warm?

The docs give one rule of thumb: "Pick your model and effort level at the top of a session, then save /compact for natural breaks between tasks." In practice:

1. Choose model, effort and fast mode before you start, not halfway through.
2. Connect the MCP servers you need before the first message.
3. Run /compact between tasks rather than letting auto-compaction trigger mid-task.
4. Use /rewind instead of /compact to abandon a dead end.
5. Expect the first turn after a long break, a resume of an old session or an upgrade to be slow; it is the cache rebuilding. The sessions guide explains what resuming reloads.

Caching only helps if the start of each request stays the same, and a stable, reusable opening prompt does the same for you as a person. Kipt keeps prompts and skills as Markdown in a private GitHub repo you own, so your standard session starters are the same every time you reach for them.