Claude Code uses prompt caching Anthropic's Claude Code uses prompt caching to avoid reprocessing unchanged parts of API requests, organized by layers of system prompt, project context, and conversation. Actions like switching models, changing effort level, or toggling fast mode invalidate the cache, causing slower and more expensive subsequent requests. disable it disable-prompt-caching . 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 https://platform.claude.com/docs/en/build-with-claude/prompt-caching 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, 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 mode /docs/en/permission-modes analyze-before-you-edit-with-plan-mode and skill loading /docs/en/skills , 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. See Switching models switching-models below. 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. See Changing effort level changing-effort-level below. 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 the Claude Platform on AWS /docs/en/claude-platform-on-aws Claude API https://platform.claude.com/docs Bedrock 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 gateway ANTHROPIC BASE URL or LLM gateway /docs/en/llm-gateway data usage /docs/en/data-usage . Wherever the cache lives, entries expire after a period of inactivity, and Cache lifetime cache-lifetime below 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 models switching-models Changing effort level changing-effort-level Turning on fast mode turning-on-fast-mode Connecting or disconnecting an MCP server connecting-or-disconnecting-an-mcp-server Enabling or disabling a plugin enabling-or-disabling-a-plugin Denying an entire tool denying-an-entire-tool Compacting the conversation compacting-the-conversation Upgrading Claude Code upgrading-claude-code Switching models Each model has its own cache. Switching with means the next request reads the entire conversation history with no cache hits, even though the content is identical. The /docs/en/model-config setting-your-model /model resolves to Opus during plan mode and Sonnet during execution, so each plan-mode toggle is a model switch and starts a fresh cache. /docs/en/model-config opusplan-model-setting opusplan model setting Automatic model fallback /docs/en/model-config automatic-model-fallback on 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 by effort level /docs/en/model-config adjust-effort-level as 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 Enabling fast mode /docs/en/fast-mode adds 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 /docs/en/fast-mode understand-the-cost-tradeoff , 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 switching-models , 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 speed /docs/en/fast-mode handle-rate-limits after 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 the advisor tool /docs/en/advisor is an exception: its definition sits after the cache breakpoint, so enabling or disabling /advisor keeps the cached prefix intact. Whether an MCP server /docs/en/mcp change does this depends on whether its tools are deferred by tool search /docs/en/mcp scale-with-mcp-tool-search or 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 when tool search is unavailable or disabled /docs/en/mcp configure-tool-search , such as on Haiku models, on Vertex AI, or with a custom ANTHROPIC BASE URL gateway. It also happens for a server or tool marked, and for definitions kept upfront by alwaysLoad threshold-based loading /docs/en/mcp configure-tool-search . reconnects automatically after a transient failure /docs/en/mcp automatic-reconnection . A connected server can also push a dynamic tool update /docs/en/mcp dynamic-tool-updates that 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 Plugins /docs/en/plugins bundle 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 /docs/en/plugins-reference mcp-servers . Enabling or disabling one follows the same rules as connecting or disconnecting an MCP server 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 or start a new session. The cost, whether appended announcements or a full re-read, shows up on the first turn after the reload, not when you run /docs/en/discover-plugins apply-plugin-changes-without-restarting /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 cache-lifetime , the next request reads the older cache entry instead of rebuilding. Denying an entire tool Adding a bare tool name like Bash or WebFetch as a deny rule /docs/en/permissions manage-permissions removes 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 /docs/en/settings when-edits-take-effect . 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 connecting-or-disconnecting-an-mcp-server , 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 Compaction /docs/en/context-window what-survives-compaction replaces 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-update /docs/en/setup auto-updates downloads 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 session /docs/en/sessions resume-a-session after 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 repository editing-files-in-your-repository Editing CLAUDE.md mid-session editing-claude-md-mid-session Changing output style changing-output-style Changing permission mode changing-permission-mode Invoking skills and commands invoking-skills-and-commands Running running-%2Frecap /recap Rewinding the conversation rewinding-the-conversation Spawning a subagent subagents-and-the-cache 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