Text of code.claude.com › docs › en › prompt-caching as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

How Claude Code uses prompt caching - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. Prompt caching makes Claude Code faster and more cost-efficient. Without caching, the API would reprocess your full history on every turn. With caching, it reuses what it already processed, bills the re-read at the cached token rate , and fully processes only what changed.

Claude Code handles prompt caching for you, unless you disable it . It is still useful to know how prompt caching works, because some actions invalidate the cache and make the next response slower and more expensive while it rebuilds. This page covers which actions those are, why some settings wait for a restart to apply, and how to check cache performance when usage looks high. How the cache is organized Each time you send a message in Claude Code, it makes a new API request.

The model doesn’t remember anything between requests, so Claude Code re-sends the full context: the system prompt, your project context, every prior message and tool result, and your new message. New content is appended at the end, which means most of each request is identical to the one before it. Prompt caching is how the API avoids reprocessing the part that didn’t change. The API caches by matching the start of each request, called the prefix, against content it recently processed.

On a normal turn, the prefix is the entire previous request and only the latest exchange is new. The match is exact, so a change anywhere in the prefix recomputes everything after it. There is no per-file or per-segment caching. See how prompt caching works in the API reference for the underlying mechanism. To get the most out of prefix matching, Claude Code orders each request so content that rarely changes between turns comes first: Layer Content Changes when System prompt Core instructions, tool definitions The set of loaded tool definitions changes Project context CLAUDE.md, auto memory, unscoped rules Session starts, or after /clear or /compact Conversation Your messages, Claude’s responses, tool results Every turn An addition to the conversation layer leaves the system prompt and project context cached.

A change to the system prompt invalidates everything, because all later content now sits behind a different prefix. The third column gives common triggers rather than an exhaustive list, and the sections below cover the full set. The prefix-match rule explains most of the behaviors on this page. Plan mode and skill loading , for example, append their instructions as conversation messages, so the cached prefix stays intact.

Two settings don’t appear in the layer table but still affect what stays cached: Model : each model has its own cache. Switching models recomputes the entire request even when the content is identical. See Switching models below. Effort level : on most models, each effort level has its own cache, so changing effort mid-session recomputes the entire request. With an API key or a Claude subscription, the cache stays intact by default on Fable 5.1 and later, Opus 5.5, Sonnet 5.5, and Haiku 5.5.

See Changing effort level below. Pick your model and effort level at the top of a session, then save /compact for natural breaks between tasks. The fewer changes you make mid-task, the higher your cache hit rate. Where the cache lives Caching happens server-side, in whichever infrastructure serves your model. Where that is depends on how you authenticate: API key, Claude subscription, or Claude Platform on AWS : the cache lives in Anthropic’s infrastructure, accessed through the Claude API Amazon Bedrock or Google Cloud’s Agent Platform : the cache lives in your cloud provider’s serving infrastructure Microsoft Foundry : depends on the deployment’s hosting option .

Hosted on Azure deployments are served on Azure infrastructure; Hosted on Anthropic deployments are served on Anthropic’s infrastructure Custom ANTHROPIC_BASE_URL or LLM gateway : the cache lives wherever your requests are forwarded, and whether caching works depends on the gateway Claude Code also appends system context mid-conversation, such as file-change notices, and marks that block for caching on every provider and connection unless you set CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS , in which case that block is sent uncached.

At the provider’s own endpoint, Amazon Bedrock and its Mantle endpoint , Google Cloud’s Agent Platform, and Microsoft Foundry cache the block the same way the Claude API does. When your requests pass through an LLM gateway , a custom ANTHROPIC_BASE_URL , or a cloud provider base-URL override such as ANTHROPIC_BEDROCK_BASE_URL , what stays cached depends on how the gateway handles the cache_control markers Claude Code sends: Forwards them unchanged : the block and your conversation cache the same as at the provider’s own endpoint.

Rejects the marked request with a 400 error naming cache_control : Claude Code re-sends the request with the marker moved off the block and onto your last conversation message, and keeps it there until Claude Code exits. The block bills as uncached input; your conversation stays cached. Removes the markers while returning success : your entire conversation history bills as uncached input on every turn. A gateway that converts block-form system content to a plain string drops the marker the same way.

For what each provider stores and processes, see data usage . Wherever the cache lives, entries expire after a period of inactivity, and Cache lifetime below covers the TTL and how to extend it. Actions that invalidate the cache These actions can cause the next request to miss part or all of the cache. You see a one-time slower, more expensive turn, after which the new prefix is cached. Most of them are avoidable mid-task once you know they have a cost.

A model switch can feel free until you notice the slower turn that follows. Switching models Changing effort level Turning on fast mode Connecting or removing an MCP server Enabling or disabling a plugin Denying an entire tool Compacting the conversation Accumulating many images Upgrading Claude Code Switching models Each model has its own cache. Switching with /model means the next request reads the entire conversation history with no cache hits, even though the content is identical.

When you run /model at the terminal, Claude Code asks you to confirm the switch only while the cache is still warm and the new model isn’t the one that produced the last response. The cache stays warm for one cache TTL after Claude Code last sent a request in this conversation or Claude last responded. Once that time passes, the cache has expired, so Claude Code switches without asking. Before v2.1.238, Claude Code didn’t check the cache TTL and asked even after the cache had expired.

You can also require this confirmation or skip it with a PreModelSwitch hook . The opusplan model setting resolves to Opus during plan mode and Sonnet during execution, so each plan-mode toggle is a model switch and starts a fresh cache. Automatic model fallback on Fable models, Opus 5.5, Sonnet 5.5, and Opus 5 is also a model switch. When a safety classifier flags a request in a category that has a fallback model and Claude Code re-runs the request on that model, the session continues there.

When a skill or command’s frontmatter names a model other than the session’s current model, that turn is also a model switch: the next request reads the entire conversation history with no cache hits. The session model resumes on your next prompt. A context: fork skill sets the forked subagent’s model instead. Changing effort level On most models, changing the effort level mid-session means the next request reads the entire conversation history with no cache hits.

While the cache is still warm, Claude Code asks you to confirm the change first

The rest of this page is on the live site.