Claude Code Prompt Caching: Stop Paying for the Same Context

A practical guide to cache prefixes, token usage, TTLs, invalidation, and the habits that keep long Claude Code sessions efficient. A long coding session can look expensive because the token counter is enormous. But the useful question is not how many tokens appeared in the context. It is how many were processed from scratch—and how many arrived through a warm cache. Claude Code prompt caching can reuse stable context across turns, reducing the cost of repeatedly processing the same prefix. The least interesting way to reduce Claude Code token usage is to shave five words from every request. The more important lever sits underneath the conversation: prompt caching. Claude Code repeatedly sends a large context containing system instructions, tool definitions, project guidance, and conversation history. If the beginning of the request matches an earlier request, Anthropic can reuse that stable prefix instead of processing it again at the full input-token rate. That changes how you should read a large token number. A session that has touched hundreds of millions of cached tokens is not equivalent to one that processed hundreds of millions of new input tokens. A high cached-token count can indicate that Claude Code is reusing an established context rather than rebuilding it on every turn. The better diagnostic is a ratio: cache read ────────────── total input context If cache reads remain high while fresh input stays proportionate to the work being added, the session is behaving efficiently. If cache reads suddenly collapse, look for a prefix change before blaming the model. What Claude Code prompt caching actually reuses Prompt caching is based on exact prefix matching . It does not independently cache each repository file, paragraph, or tool. Claude Code builds a request in a stable order and the cache can reuse the matching beginning. The conceptual sequence is: SYSTEM Claude Code instructions and tool definitions PROJECT CLAUDE.md files, rules, memory, and project context CONVERSATION messages and tool results accumulated in the session NEW TURN the latest request and whatever follows it On the first request, the system processes the context and writes reusable material into the cache. On the next request, the unchanged prefix can be read from that cache while the latest exchange is processed normally. The reusable conversation prefix grows as the session grows. Cache-read input is priced at roughly one-tenth of standard input, although cache creation and model pricing still matter. Anthropic’s Claude Code documentation describes cache reads as billed at approximately 10% of standard input-token cost. That is why a long, coherent session can remain economical even when its nominal context becomes large. Do not flatten the accounting into “every cached token is free.” There are separate measurements: cache_creation_input_tokens records tokens written to a cache. cache_read_input_tokens records reusable tokens read from it. Fresh input, output, and model-specific rates still contribute to usage. The practical objective is therefore not the largest possible context. It is a stable, relevant prefix with a high reuse rate. Cache creation and cache reads tell different stories Cache creation is the write; cache read is the reuse. A healthy workflow watches both instead of treating all input tokens alike. Imagine a project begins with 40,000 tokens of instructions, tool definitions, and repository context. The first turn may need to process and cache that prefix. The second turn can reuse it and add only the incremental conversation. If the prefix remains stable over ten productive turns, the initial write has supported repeated low-cost reads. Now imagine changing the model after turn eight. The new model uses a separate cache, so the existing prefix cannot simply carry over. The next request rebuilds context for that model. This is why token optimization is closer to systems engineering than copy editing. The expensive event is often a transition: warm prefix → configuration change → cold prefix → cache rebuild A high cache-read number is usually a good sign, but it is not a quality metric by itself. You can cheaply reuse an irrelevant conversation for hours. Efficiency needs two tests: Is the prefix being reused? Is the reused prefix still useful for the task? The first saves tokens. The second saves judgment. Stable cache prefixes can improve latency and economics, but only when the retained context still serves the work. How the Claude Code cache grows turn by turn Each turn can reuse the matching prefix and append new conversation, making continuity cheaper than repeatedly reconstructing the same context. A simplified three-turn session looks like this: TURN 1 [system][project][message 1][response 1] processed and cached TURN 2 [cached matching prefix][message 2][response 2] TURN 3 [longer cached matching prefix][message 3][response 3] This explains an apparent paradox: longer sessions can be efficient, while restarting constantly can be wasteful. If each new session reloads the same tool definitions, repository rules, and project context, you keep paying the cache-creation cost. Preserving a relevant session lets the accumulated prefix work for you. But “never start fresh” is equally crude advice. When the task changes completely, stale context can produce wrong assumptions, distract the model, and make verification harder. The right boundary is semantic, not superstitious: Continue when the next task depends on the same repository state and decisions. Use /compact at a natural boundary when you need a shorter working history. Use /clear or a new session when the context is no longer an asset. Claude Code’s current documentation says /compact uses the cached conversation prefix to produce a summary, then begins a shorter conversation cache from that summary. Compaction changes the conversation layer; it is not merely a cosmetic edit. Still, it can be the correct trade when relevance is decaying. The three cache layers—and what can invalidate them Claude Code orders system, project, and conversation context so a stable prefix can be reused across successive requests. Thinking in layers makes cache misses easier to diagnose. System layer This includes Claude Code’s base instructions and tool definitions. Changes near the beginning of the request can invalidate everything after them. According to Anthropic’s prompt-caching guide, connecting or disconnecting an MCP server changes the tool set and invalidates the cache. Upgrading Claude Code can also alter the system prompt or tools. Project layer This includes project context such as CLAUDE.md and related instructions. Claude Code deliberately keeps this layer stable during a running session. An important nuance: editing the root CLAUDE.md file during a session does not immediately rewrite the live prefix. The updated instruction is picked up after /clear, /compact, or a restart. That protects the current cache, but it also means the model may not yet be following the change you just saved. Repository file edits are different. Ordinary code changes do not inherently rewrite the cached project prefix. Tool results can communicate changed state as the conversation proceeds. Conversation layer Messages and tool results accumulate here. /compact replaces the older conversation with a summary; rewind truncates the conversation to an earlier prefix. Skills generally append messages, preserving what came before them. These details matter because “editing any file breaks the cache” is false—and “nothing breaks unless an hour passes” is also false. The one-hour and five-minute TTLs are both real The apparent conflict comes from different access paths. Claude Code subscription sessions request a one-hour cache duration. Anthropic notes that if included plan usage is exhausted and the session moves to extra-usage credits, Claude Code can reduce that duration to five minutes. For API usage—including direct API and supported cloud platforms—the documented default cache lifetime is five minutes. A one-hour cache is available as a separate option, and Claude Code API users can request it through ENABLE_PROMPT_CACHING_1H=1. So the operational rule is not “Claude always caches for one hour.” It is: subscription capacity available → typically requests 1 hour API default → 5 minutes API with 1-hour option → 1 hour subscription using extra credits → may fall back to 5 minutes TTL expiry does not corrupt the conversation. It means the next request may need to create the cache again. If you return after a long break, the first turn can be more expensive; subsequent matching turns can become warm again. That also means there is no universal reason to throw away a useful session after the TTL expires. A fresh session must load context too. Choose based on relevance and correctness, not the emotional sting of one cold request. What reliably breaks a warm Claude Code cache The most useful invalidators to remember are: Switching models. Caches are model-specific. Changing the model requires a separate prefix. Changing MCP connections. The available tool definitions change. Compacting. The conversation layer is replaced by a summary and a new shorter cache begins. Upgrading Claude Code. System instructions or tool definitions can change. Letting the TTL expire. The cached prefix ages out and must be written again. Working from a different directory or machine. Claude Code cache sharing is effectively tied to the environment and working directory. Effort-level changes, by contrast, do not alter the cache key according to the current documentation. Parallel sessions launched from the same directory can sometimes share matching prefixes. Worktrees use different directories, so they do not share that cache. Sequential sessions are more likely to match when the Git state and opening prompt are consistent. This suggests a deeper rule: cache locality follows workflow locality. A practical workflow to save tokens in Claude Code Do not contort the work to worship the cache. Use a few habits that also improve engineering clarity. 1. Put stable guidance before transient instructions Keep durable conventions in CLAUDE.md: commands, architecture boundaries, test expectations, and repository-specific rules. Keep the current task in the conversation. Stable context belongs in the stable prefix. 2. Avoid casual model switching Switch when a different model materially improves the work, not as a reflex between planning and execution. A model change may be worth the cache rebuild; it should simply be intentional. 3. Connect MCP tools before the main run If a task needs a database, browser, issue tracker, or design tool, establish those connections before building a long conversational prefix. Mid-session tool changes move an early part of the request. 4. Compact at decision boundaries Use /compact after a milestone: investigation complete, implementation complete, or one subproblem resolved. Ask the summary to preserve constraints, changed files, failed attempts, commands, and the next verification step. 5. Start fresh when context becomes misleading The costliest token is not the uncached one. It is the cached assumption that causes a bad change. A clean handoff should preserve: goal current repository state decisions and constraints files changed tests run and results open risks next concrete action 6. Measure before inventing rituals Inspect the usage telemetry available to you. Watch for sudden changes in cache reads, then correlate them with model changes, compaction, MCP changes, upgrades, directories, and long idle periods. Token dashboards are most useful when they separate fresh input, output, cache creation, and cache reads instead of presenting one intimidating total. The real optimization target is continuity with boundaries Prompt caching rewards continuity. Good engineering rewards boundaries. Those ideas are not enemies. You want stable instructions, consistent tools, and enough session history to avoid rediscovering the project every ten minutes. You also want explicit task boundaries, compact handoffs, and the courage to discard context that has become noise. The mature Claude Code workflow does both: preserve the prefix while it remains an asset → compact when the history exceeds its usefulness → clear when the task identity changes → verify the new state Saving tokens is a consequence of keeping the system legible. Once you understand the prefix, the token dashboard stops looking like a slot machine and starts looking like observability. Stay curious 🍓 PS: On your next long session, note the time of every model switch, MCP connection, compaction, and restart. Compare those moments with cache-read changes. One afternoon of evidence will teach you more than a month of token folklore. Reference Notes These primary sources support current technical details added during repurposing: Claude Code prompt caching — official explanation of prefix order, invalidation events, TTLs, model switching, directories, compaction, and cache metrics. Claude Code costs — official guidance for monitoring and managing Claude Code token usage and cost. Anthropic API prompt caching — official API behavior, cache lifetime options, pricing concepts, and cache-token fields. Claude Code Prompt Caching: Stop Paying for the Same Context was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.