Claude Code Caching Explained: A Practical Guide to Saving Money and Speeding Up

When using Claude Code for development, have you ever noticed that responses are sometimes lightning-fast and other times noticeably slower — with API costs fluctuating accordingly? The key mechanism behind this is Prompt Caching. This article systematically breaks down how this feature works, including its core principles, invalidation rules, and best practices, so you can meaningfully boost efficiency and reduce costs in your everyday workflow.

What Is Prompt Caching

Prompt Caching is essentially an intelligent memory mechanism. Without caching, every interaction with Claude requires the model to re-read all previous conversation history and context. With caching, it can remember content it has already processed and focus only on what's new. This dramatically speeds up responses and eliminates the overhead of redundant processing.

Technical Background: KV Cache and LLM Inference

Prompt Caching is underpinned by the KV Cache (Key-Value Cache) mechanism used in large language model inference. In the Transformer architecture, each token passing through the attention layers generates corresponding Key and Value vectors. When processing identical prefix text, these vectors can be reused without recomputation — this is the physical foundation of cache-based acceleration. Anthropic wraps this low-level mechanism into a developer-friendly Prompt Caching API, allowing developers to benefit without needing to understand model internals. From a cost perspective, Anthropic's official data shows that cache-hit token reads cost approximately 10% of normal input tokens, while writing to cache costs about 125% of normal input — meaning caching only pays off when the same prefix is reused multiple times.

The system manages this process automatically, but understanding how it works helps you avoid many common pitfalls. Caching isn't magic — it follows clear engineering rules, and once you understand them, you can actively guide it to work in your favor.

The Three-Layer Cache Structure and Invalidation Cascade

Claude Code organizes requests into three layers:

• System Prompt Layer (top): Contains core instructions and tool definitions — rarely changes.
• Project Context Layer (middle): Project configuration files such as CLAUDE.md.
• Live Conversation Layer (bottom): The current, ongoing conversation.

The critical insight here is the prefix matching mechanism: lower layers can only reuse their cache if upper layers remain unchanged. Once a higher layer changes, the entire cache chain below it is invalidated — this is the "invalidation cascade."

The Engineering Logic Behind Prefix Matching

Prefix matching stems from the autoregressive computation properties of the Transformer architecture. When processing text, each token's attention computation depends on the KV vectors of all preceding tokens. This means only when a piece of text is identical from the very beginning can intermediate computation results be reused — any change to the prefix invalidates all subsequent token computations, creating the "invalidation cascade." This makes caching highly sensitive to content ordering: placing stable system prompts before conversation context is the golden rule for leveraging the cache. This also explains why Claude Code places the system prompt layer at the top — it's the least likely to change across requests and the best candidate for long-term caching.

Beyond content itself, two hidden "keys" determine cache validity: model and effort level. The Opus model's cache is completely isolated from Sonnet's, and a high effort level's cache does not carry over to the default level.

Therefore, the best practice is: decide on your model and effort settings before starting a task and avoid switching mid-session, which would invalidate the cache and slow down requests.

Where the Cache Lives

The cache is stored server-side. The specific location depends on how you're authenticated: when using an API key or a direct subscription, the cache resides on Anthropic's servers; when accessing via Bedrock or Vertex AI, the cache is held by the respective cloud provider. Understanding this helps you grasp the cache's scope and lifecycle.

Operations That Break the Cache

Knowing the "danger zones" is the first step to avoiding performance degradation. The following operations will invalidate Claude Code's cache:

Switching Models or Effort Levels

Each model and effort level has its own independent cache. Using /model to switch from Sonnet to Opus, or /effort to adjust the workload level, will invalidate the cache. Pay special attention to the Opus Plan model — its automatic switching between planning and execution modes also triggers invalidation. Fortunately, the system usually warns you before these operations.

MCP Server and Tool Permission Changes

Since tool definitions are part of the system prompt layer, any operation that changes the available tool set — such as connecting or disconnecting an MCP server — will invalidate the cache. Similarly, if you completely disable a tool (like Bash) mid-conversation, it modifies the system prompt and causes invalidation.

MCP Protocol and Its Relationship to Tool Definitions

MCP (Model Context Protocol) is an open protocol introduced by Anthropic in 2024 to standardize how AI models connect to external tools and data sources. In Claude Code, each MCP server connection injects Tool Definitions into the system prompt layer — these definitions describe which functions the model can call and what their parameter formats are. Since tool definitions are part of the system prompt, adding or removing any MCP server changes this text and breaks the cache prefix. Understanding this mechanism helps you develop smarter configuration strategies: connect all necessary MCP servers at the start of a work session rather than adding and removing them dynamically, which keeps the cache stable.

Note: scope-limited permissions like Bash(rm) are safe and do not affect the cache.

Compacting Conversations and Upgrading the Software

Running /compact replaces conversation history with a summary, which invalidates the conversation layer cache — but the system prompt and project context caches remain intact. It's a good idea to proactively compact between tasks. Additionally, after upgrading Claude Code, the first request may need to rebuild the cache since the system prompt may have changed — restoring a long session at this point could incur a significant extra cost.

Operations That Are Cache-Safe

In contrast to the danger zones, many common operations are completely cache-safe and can be used without worry:

• Editing code files: Completely safe — file contents are read on demand and appended to the end of the context.
• Switching permission modes, invoking skills, running /recap: None of these affect the cache prefix.
• /rewind command: Highly efficient — it simply truncates the conversation, and the remaining portion can still hit the previous cache.

You might not have noticed: editing CLAUDE.md or changing output style won't invalidate the cache, but the changes also won't take effect immediately — they apply at the next compaction or session restart. This is because these configurations are loaded into the system prompt layer at session start.

Lifecycle, Monitoring, and Special Scenarios

Cache Lifecycle (TTL)

The cache doesn't last forever. There are currently two TTL (Time-To-Live) options: 5 minutes and 1 hour. The 5-minute option costs less; the 1-hour option keeps the cache "warm" even after longer interruptions. Subscribers default to 1-hour TTL; API key users default to 5 minutes, but can enable the 1-hour option via an environment variable.

TTL and Cloud Cache Infrastructure

TTL (Time-To-Live) is a standard concept in distributed caching systems that controls how long cached data remains valid. Claude's two-tier TTL design reflects the trade-off between latency costs and storage costs across different use cases: 5-minute TTL suits high-frequency, short-duration tasks with lower storage overhead; 1-hour TTL suits long tasks that may be interrupted, avoiding "cold start" costs. Notably, the cache is stored server-side (at Anthropic, AWS Bedrock, or Google Vertex AI), meaning it is isolated per user account rather than per device — but Claude Code further restricts the cache scope on the client side to a single directory on a single machine, an engineering decision made to ensure context consistency rather than a limitation of the underlying API.

The cache's effective scope is strictly limited to one directory on one machine. Caches in different folders are independent of each other, and even switching Git branches within the same folder means a new session cannot reuse the cache from the previous branch.

How to Monitor Cache Efficiency

The API returns two key metrics: cache_creation_input_tokens (tokens written to cache) and cache_read_input_tokens (tokens read from cache). A healthy system should maintain a high read-to-creation ratio. If creation values are consistently high, the cache may be invalidating frequently — investigate whether any improper operations are causing this.

Sub-agents vs. Forks

These are two advanced scenarios that are easy to confuse:

• Sub-agent: Creates an independent conversation and cache. The first call requires a warm-up but doesn't affect the parent agent's cache.
• Fork: Inherits the parent agent's cache and can read it immediately, making startup very fast.

Two Scaling Patterns in Agent Architecture

The distinction between sub-agents and forks reflects two scaling philosophies in AI agent system architecture. The sub-agent pattern is similar to independent service calls in a microservices architecture: each sub-agent has its own context window and cache space, communicating with the parent agent via message passing — well-suited for parallel tasks that require fully isolated execution environments. The fork pattern resembles process forking (fork()) in operating systems: the child process inherits the parent's memory state. In Claude Code's context, this means inheriting the parent agent's cache prefix, enabling very fast startup — ideal for spawning multiple slightly different execution paths from the same context. When designing complex multi-step AI workflows, understanding the caching characteristics of these two patterns can significantly impact overall system response time and token consumption.

Understanding the difference helps you make more efficient architectural choices for complex tasks.

Advanced Configuration and Best Practices

As an advanced option, you can completely disable Prompt Caching via environment variables for debugging specific issues — either globally or only for specific models (such as Haiku, Sonnet, or Opus). Organization administrators can also configure caching policies uniformly through managed settings. Unless necessary, disabling the cache is not recommended, as it will significantly impact performance and cost.

To summarize the core principle — understand the prefix matching mechanism and keep prefixes stable:

1. Configure your model and effort level at the start of a session and avoid changing them mid-way;
2. Proactively run /compact between tasks;
3. Prefer /rewind for rollbacks rather than restarting the session;
4. Regularly monitor cache performance metrics to catch unexpected invalidations early.

Master these techniques, and you'll be able to make caching work for you — enjoying the full power of Claude Code while keeping costs under control.

Key Takeaways