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.
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.
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.
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 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
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.
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:
The practical objective is therefore not the largest possible context. It is a stable, relevant prefix with a high reuse rate.
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:
The first saves tokens. The second saves judgment.
A simplified three-turn session looks like this:
TURN 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]
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:
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.
Thinking in layers makes cache misses easier to diagnose.
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.
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.
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 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 hourAPI default → 5 minutesAPI with 1-hour option → 1 hoursubscription 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.
The most useful invalidators to remember are:
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.
Do not contort the work to worship the cache. Use a few habits that also improve engineering clarity.
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.
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.
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.
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.
The costliest token is not the uncached one. It is the cached assumption that causes a bad change.
A clean handoff should preserve:
goalcurrent repository statedecisions and constraintsfiles changedtests run and resultsopen risksnext concrete action
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.
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.
These primary sources support current technical details added during repurposing:
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.