{"slug": "claude-code-prompt-caching-stop-paying-for-the-same-context", "title": "Claude Code Prompt Caching: Stop Paying for the Same Context", "summary": "Anthropic's Claude Code uses prompt caching to reduce token costs by reusing stable context prefixes across turns, with cache reads billed at approximately 10% of standard input-token cost, making long, coherent sessions economical. The key efficiency metric is the ratio of cache reads to total input context, and cache effectiveness depends on exact prefix matching, so model changes or prefix breaks trigger expensive cache rebuilds.", "body_md": "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.\n\nThe least interesting way to reduce Claude Code token usage is to shave five words from every request.\n\nThe more important lever sits underneath the conversation: prompt caching.\n\nClaude 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.\n\nThat 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.\n\nThe better diagnostic is a ratio:\n\n```\ncache read──────────────total input context\n```\n\nIf 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.\n\nPrompt 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.\n\nThe conceptual sequence is:\n\n```\nSYSTEM       Claude Code instructions and tool definitionsPROJECT      CLAUDE.md files, rules, memory, and project contextCONVERSATION messages and tool results accumulated in the sessionNEW TURN     the latest request and whatever follows it\n```\n\nOn 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.\n\nAnthropic’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.\n\nDo not flatten the accounting into “every cached token is free.” There are separate measurements:\n\nThe practical objective is therefore not the largest possible context. It is a stable, relevant prefix with a high reuse rate.\n\nImagine a project begins with 40,000 tokens of instructions, tool definitions, and repository context.\n\nThe 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.\n\nNow 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.\n\nThis is why token optimization is closer to systems engineering than copy editing. The expensive event is often a transition:\n\n```\nwarm prefix→ configuration change→ cold prefix→ cache rebuild\n```\n\nA 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:\n\nThe first saves tokens. The second saves judgment.\n\nA simplified three-turn session looks like this:\n\n```\nTURN 1[system][project][message 1][response 1]          processed and cachedTURN 2[cached matching prefix][message 2][response 2]TURN 3[longer cached matching prefix][message 3][response 3]\n```\n\nThis explains an apparent paradox: longer sessions can be efficient, while restarting constantly can be wasteful.\n\nIf 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.\n\nBut “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:\n\nClaude 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.\n\nThinking in layers makes cache misses easier to diagnose.\n\nThis includes Claude Code’s base instructions and tool definitions. Changes near the beginning of the request can invalidate everything after them.\n\nAccording 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.\n\nThis includes project context such as CLAUDE.md and related instructions. Claude Code deliberately keeps this layer stable during a running session.\n\nAn 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.\n\nRepository 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.\n\nMessages 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.\n\nThese details matter because “editing any file breaks the cache” is false—and “nothing breaks unless an hour passes” is also false.\n\nThe apparent conflict comes from different access paths.\n\nClaude 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.\n\nFor 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.\n\nSo the operational rule is not “Claude always caches for one hour.” It is:\n\n```\nsubscription capacity available  → typically requests 1 hourAPI default                       → 5 minutesAPI with 1-hour option            → 1 hoursubscription using extra credits  → may fall back to 5 minutes\n```\n\nTTL 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.\n\nThat 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.\n\nThe most useful invalidators to remember are:\n\nEffort-level changes, by contrast, do not alter the cache key according to the current documentation.\n\nParallel 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.\n\nThis suggests a deeper rule: cache locality follows workflow locality.\n\nDo not contort the work to worship the cache. Use a few habits that also improve engineering clarity.\n\nKeep durable conventions in CLAUDE.md: commands, architecture boundaries, test expectations, and repository-specific rules. Keep the current task in the conversation.\n\nStable context belongs in the stable prefix.\n\nSwitch 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.\n\nIf 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.\n\nUse /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.\n\nThe costliest token is not the uncached one. It is the cached assumption that causes a bad change.\n\nA clean handoff should preserve:\n\n```\ngoalcurrent repository statedecisions and constraintsfiles changedtests run and resultsopen risksnext concrete action\n```\n\nInspect 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.\n\nPrompt caching rewards continuity. Good engineering rewards boundaries.\n\nThose ideas are not enemies.\n\nYou 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.\n\nThe mature Claude Code workflow does both:\n\n```\npreserve the prefix while it remains an asset→ compact when the history exceeds its usefulness→ clear when the task identity changes→ verify the new state\n```\n\nSaving 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.\n\nStay curious 🍓\n\n*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.*\n\nThese primary sources support current technical details added during repurposing:\n\n[Claude Code Prompt Caching: Stop Paying for the Same Context](https://pub.towardsai.net/claude-code-prompt-caching-stop-paying-for-the-same-context-b6146dc56431) was originally published in [Towards AI](https://pub.towardsai.net) on Medium, where people are continuing the conversation by highlighting and responding to this story.", "url": "https://wpnews.pro/news/claude-code-prompt-caching-stop-paying-for-the-same-context", "canonical_source": "https://pub.towardsai.net/claude-code-prompt-caching-stop-paying-for-the-same-context-b6146dc56431?source=rss----98111c9905da---4", "published_at": "2026-07-27 20:01:01+00:00", "updated_at": "2026-07-27 20:11:56.605795+00:00", "lang": "en", "topics": ["large-language-models", "ai-tools", "ai-infrastructure"], "entities": ["Anthropic", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/claude-code-prompt-caching-stop-paying-for-the-same-context", "markdown": "https://wpnews.pro/news/claude-code-prompt-caching-stop-paying-for-the-same-context.md", "text": "https://wpnews.pro/news/claude-code-prompt-caching-stop-paying-for-the-same-context.txt", "jsonld": "https://wpnews.pro/news/claude-code-prompt-caching-stop-paying-for-the-same-context.jsonld"}}