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. Seehow prompt caching worksin 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, output style | The set of loaded tool definitions changes, or Claude Code is upgraded |
| 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 |
Plan modeand skill , for example, append their instructions as conversation messages, so the cached prefix stays intact. Two settings aren’t part of the prompt text at all, so they don’t appear in the layer table, but both are part of the cache key:
Model: each model has its own cache. Switching models recomputes the entire request even when the content is identical. SeeSwitching modelsbelow.Effort level: each effort level has its own cache for the same model. Changing it mid-session recomputes the entire request, and Claude Code asks you to confirm before applying the change. SeeChanging effort levelbelow.
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: the cache lives in Anthropic’s infrastructure, accessed through theClaude Platform on AWSClaude APIBedrock or Vertex AI: the cache lives in your cloud provider’s serving infrastructure** Foundry**: requests route to Anthropic’s infrastructure** Custom**: the cache lives wherever your requests are forwarded, and whether caching works depends on the gatewayANTHROPIC_BASE_URL
orLLM gateway data usage. Wherever the cache lives, entries expire after a period of inactivity, and
Cache lifetimebelow covers the TTL and how to extend it.
Actions that invalidate the cache #
These actions 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 modelsChanging effort levelTurning on fast modeConnecting or disconnecting an MCP serverEnabling or disabling a pluginDenying an entire toolCompacting the conversationUpgrading Claude Code
Switching models
Each model has its own cache. Switching withmeans the next request reads the entire conversation history with no cache hits, even though the content is identical. The
/model
opusplan
model settingAutomatic model fallbackon Fable 5 is also a model switch. When a safety classifier flags a request, Claude Code re-runs it on the default Opus model and the session continues there.
Changing effort level
The cache is keyed byeffort levelas well as model, so switching with
/effort
means the next request reads the entire conversation history with no cache hits. Once a conversation has started, Claude Code shows a confirmation dialog before applying an effort change that would invalidate the cache. A change that resolves to the same level already in effect, such as setting the model’s default explicitly, skips the dialog and keeps the cache.
Turning on fast mode
Enablingfast modeadds a request header that is part of the cache key, so the next request reads the entire conversation history with no cache hits. Those uncached input tokens are billed at
fast mode rates, which is why turning it on at the start of a session costs less than turning it on deep into a long one. Enabling fast mode from a non-Opus model also
switches your model, which starts a fresh cache on its own. The cost applies once per conversation. After the first fast mode turn, Claude Code keeps sending the header and varies only the request’s speed setting, which is not part of the cache key. Turning fast mode off, the
automatic fallback to standard speedafter a rate limit, and turning it back on later all keep the cache.
/clear
and /compact
reset this, since they rebuild the cache at those points anyway. Keeping the header across toggles requires Claude Code v2.1.86 or later. On earlier versions, every fast mode toggle and rate-limit fallback invalidates the cache.
Connecting or disconnecting an MCP server
Tool definitions sit in the system prompt layer, so the cache invalidates when the set of tool definitions in the request changes between turns. Toggling theadvisor toolis an exception: its definition sits after the cache breakpoint, so enabling or disabling
/advisor
keeps the cached prefix intact. Whether an MCP serverchange does this depends on whether its tools are deferred by
tool searchor loaded into the prefix:
Deferred tools, the default on supported models: a server connecting, disconnecting, or changing its tool list only appends new content and doesn’t disturb anything already cached.Tools loaded into the prefix: any change to them invalidates the cache. This happens whentool search is unavailable or disabled, such as on Haiku models, on Vertex AI, or with a customANTHROPIC_BASE_URL
gateway. It also happens for a server or tool marked, and for definitions kept upfront byalwaysLoad
threshold-based . reconnects automatically after a transient failure. A connected server can also push a
dynamic tool updatethat changes its tool list. Editing your MCP config does not by itself change the cache. The new config takes effect only after a restart, which is when the server connects or disconnects.
Enabling or disabling a plugin
Pluginsbundle several component types, and the cost of a change depends on which components the plugin provides. Skills, commands, agents, hooks, LSP servers, monitors, and themes never invalidate the cache: anything they add to the request is appended after the existing conversation, so the next request pays for the new content but still reads everything before it from the cache. The exception is a plugin that provides
MCP servers. Enabling or disabling one follows the same rules as connecting or disconnecting an MCP server: the cache survives when the server’s tools are deferred, and the next request re-reads the entire conversation when they load into the prefix. Plugin changes apply when you run
/reload-plugins
/plugin install
, /plugin enable
, or /plugin disable
. As of v2.1.163, when a reload would trigger the full re-read, /reload-plugins
shows a warning and does not apply the reload. Pass --force
to apply anyway. Disabling a plugin you enabled earlier in the session restores the previous request shape. If that prefix is still within its cache lifetime, the next request reads the older cache entry instead of rebuilding.
Denying an entire tool
Adding a bare tool name likeBash
or WebFetch
as a deny ruleremoves that tool from Claude’s context entirely. Built-in tool definitions load into the system prompt layer, so adding or removing one of these rules mid-session invalidates the cache. The change takes effect on the next turn whether you add it through
/permissions
or by editing a settings file directly. Only a deny rule that matches in the tool-name position has this effect: a bare tool name, the equivalent
`Bash(*)`
form, or a [tool-name glob](/docs/en/permissions#tool-name-wildcards)like
"*"
. A glob that matches only MCP tools, such as "mcp__*"
, removes those tools the same way but leaves the cache intact when the matched tools are deferred, the default, since deferred definitions were never in the cached prefix. Scoped deny rules like
Bash(rm *)
, and all allow and ask rules, don’t change which tools Claude sees. Claude Code checks them when Claude attempts a call, leaving the prefix intact.
Compacting the conversation
Compactionreplaces your message history with a summary. By design, this invalidates the conversation layer, since the next request has a new, shorter history that doesn’t share a prefix with the old one. Claude Code reuses the system prompt layer and reloads project context from disk, which cache-hits only if CLAUDE.md and memory are unchanged since the session started. To produce the summary, Claude Code sends a one-off request with the same system prompt, tools, and history as your conversation, plus a summarization instruction appended as a final user message. Because it shares your prefix, that request reads the existing cache rather than reprocessing the full history. Most of compaction’s time goes to generating the summary, not to a cache miss. The turn that follows rebuilds the conversation cache only for the much shorter summary, so the post-compaction turn is not the slow part.
Upgrading Claude Code
A new Claude Code version typically updates the system prompt or tool definitions, so the first request after an upgrade rebuilds the cache from the top.Auto-updatedownloads new versions in the background but applies them on the next launch, never mid-session, so you see this as an uncached first turn after restarting rather than a surprise during a session. Set
DISABLE_AUTOUPDATER=1
to control when upgrades apply. Resuming a sessionafter an upgrade reprocesses the entire conversation history with no cache hits, since the history now sits behind a different system prompt. 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.
Actions that keep the cache #
These actions either append to the end of the conversation or don’t touch the request at all. Some of them, such as editing CLAUDE.md or changing output style, are also why a setting change waits for a restart to apply.Editing files in your repositoryEditing CLAUDE.md mid-sessionChanging output styleChanging permission modeInvoking skills and commandsRunning/recap
Rewinding the conversationSpawning a subagent
Editing files in your repository
File contents enter context only when Claude reads them, and reads append to the conversation. Editing a file Claude previously read does not retroactively change the earlier read in history. Instead, Claude Code appends a<system-reminder>
noting the file changed, and Claude re-reads it if needed.
Editing CLAUDE.md mid-session
Your project-root and user-level CLAUDE.md files are read once at session start and held in memory. Editing them mid-session does not invalidate the cache, but the edit also doesn’t apply. Claude keeps working with the version that was loaded at session start. The new content loads on the next/clear
, /compact
, or restart.
Nested CLAUDE.md files in subdirectoriesand rules withload later, when Claude first reads a matching file. Editing one before it loads does take effect. After it loads, the content is part of the conversation history, so a mid-session edit doesn’t retroactively change it.
paths:
frontmatter### Changing output style
Output styleis part of the system prompt, which Claude Code reads once at session start. Changing it via
/config
or the outputStyle
setting mid-session does not invalidate the cache, but the change also doesn’t apply. Claude keeps using the style that was loaded at session start. The new style loads on the next /clear
or restart.
Changing permission mode
Switching betweenpermission modes, such as from default to accept edits, does not change the system prompt or tool definitions, so mode changes are cache-safe. The exception is plan mode with the
opusplan
model switch.
Invoking skills and commands
Skillsand commandsinject their instructions as user messages at the point of invocation. Nothing earlier in the conversation changes.
Running /recap
generates a summary for display in your terminal. Unlike
/recap
/compact
, it appends the summary as command output rather than replacing your message history, so the cached prefix stays intact.
Rewinding the conversation
/rewind
editing files in your repository.
Cache lifetime #
Cached prefixes expire after a period of inactivity. Each request that hits the cache resets the timer, so the cache stays warm as long as you keep working. After a long enough gap, the next request recomputes the full input and re-establishes the cache, which is why the first turn back after stepping away can be noticeably slower. The time to live (TTL) controls how long a gap the cache survives. The API offers two: a five-minute TTL, and aone-hour TTLthat keeps the cache warm through longer breaks but
bills cache writes at a higher rate. Claude Code picks the TTL for you based on how you authenticate, and you can override it with environment variables.
On a Claude subscription
On a Claude subscription, Claude Code requests the one-hour TTL automatically. Usage is included in your plan rather than billed per token, so the longer TTL costs you nothing extra and only affects how long your cache stays warm. If you’ve gone over your plan’s usage limit and Claude Code is drawing onusage credits, you are billed for that usage, so Claude Code automatically drops the TTL to five minutes.
On an API key or third-party provider
On an API key, Bedrock, Vertex, Foundry, or Claude Platform on AWS, you pay the per-token rates, so the TTL stays at the cheaper five minutes by default. To opt into theone-hour TTL, set
ENABLE_PROMPT_CACHING_1H=1
. On Bedrock, prompt caching support, minimum cacheable prefix length, and one-hour TTL availability all vary by model. If cache token counts stay at zero, check supported models, regions, and limitsin the Bedrock documentation.
Override the TTL
SetFORCE_PROMPT_CACHING_5M=1
to force the five-minute TTL regardless of authentication. This is useful when you’re debugging cache behavior, comparing the two TTLs, or overriding an ENABLE_PROMPT_CACHING_1H
set in managed settings.
Cache scope #
In Claude Code, the cache is 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 miss each other’s cache. That includes worktrees of the same repository, since each worktree has its own working directory. Sessions you run in parallel in the same directory build matching prefixes and read each other’s cache. Sequential sessions share the prefix only when the git status snapshot at startup matches, since the system prompt also captures branch and recent commits. The underlying API cache is broader. Caches are isolated between organizations, and on some providers,between workspaces within an organization. Within those boundaries, any two requests with the same model and prefix read the same cache. For Agent SDK callers running fleets of automated processes, see
improve prompt caching across users and machinesto suppress the per-machine sections of the system prompt and share the cache across machines.
Check cache performance #
Cache performance shows up as two token counts the API reports on every response. The most direct way to watch them live is astatusline scriptthat reads the
current_usage
object:
| Field | Meaning |
|---|---|
cache_creation_input_tokens |
Tokens written to the cache on this turn, billed at the cache write rate |
cache_read_input_tokens |
Tokens served from cache on this turn, billed at roughly 10% of the standard input rate |
actions that invalidate the cachesection lists the usual causes. For visibility across an organization, the OpenTelemetry exporter reports cache read and creation tokens per user and session. See
Monitor usagefor the metric and event attribute reference.
Subagents and the cache #
Asubagentstarts its own conversation with its own system prompt and tool set, separate from the parent’s. It builds its own cache, starting with no cache hits on its first call and warming up across its own turns. Subagents use the five-minute TTL even on a subscription, since the automatic one-hour TTL applies to the main conversation. The parent’s cache is unaffected. From the parent’s side, the subagent’s call and result append to the conversation, leaving the parent’s prefix intact. A
fork, by contrast, inherits the parent’s system prompt, tools, and conversation history exactly, so its first request reads the parent’s cache. The compaction summarization call described in
Compacting the conversationuses the same prefix-sharing approach.
Disable prompt caching #
Disabling caching is occasionally useful when debugging caching behavior with a specific model or provider. To turn it off, set one of these environment variables to1
:
| Variable | Effect |
|---|---|
DISABLE_PROMPT_CACHING |
Disable for all models |
DISABLE_PROMPT_CACHING_HAIKU |
Disable for Haiku only |
DISABLE_PROMPT_CACHING_SONNET |
Disable for Sonnet only |
DISABLE_PROMPT_CACHING_OPUS |
Disable for Opus only |
DISABLE_PROMPT_CACHING_FABLE |
Disable for Fable only |
TTL variablesin the
env
block of managed settings. For normal use, leave caching enabled.
Related resources #
Lessons from building Claude Code: Prompt caching is everything: the design rationale for plan mode, deferred tool , and compactionExplore the context window: what loads into context and whenReduce token usage: strategies beyond caching for managing context sizeTrack and reduce costs: cache token tracking and TTL configuration for Agent SDK callersPrompt caching: the underlying API mechanism, breakpoints, and pricing