Prompt caching and what a long session costs
Claude Code is fast and affordable in long sessions because the unchanged start of each request is cached. A few ordinary actions break that cache, and knowing them is most of cost control.
The prefix is what gets cached
Every turn, the whole conversation is sent again. That would be ruinous if the model had to process all of it from scratch each time. It does not, because the API caches by exact prefix match: if the start of the request is identical to the last one, that part is read from the cache instead of recomputed.
The order of a request matters for exactly this reason:
A change high in this stack recomputes everything below it. A change at the bottom costs almost nothing. The whole craft of cheap long sessions is to keep the top still and let only the bottom move.
How long the cache lives
The cache has a lifetime. The main conversation gets one hour only on a Claude subscription, within plan usage. With an API key, cloud providers or usage credits it gets five minutes. Subagents, workflows, compaction and titles get five minutes by default.
If you step away longer than the lifetime, the next turn rebuilds the prefix. A session that grew past about 200K tokens while on the one-hour cache is even compacted shortly before the cache would expire. That is called idle compaction, and idleCompaction: false turns it off.
Why does a change to something near the start of the request cost more than one near the end?
What breaks the cache
Most of these are things you do for good reasons.
- Switching models. Each model has its own cache, so a switch invalidates all of it. The CLI asks for confirmation only while the cache is still warm.
opusplan. It uses one model to plan and another to execute, so every plan-mode toggle is a model switch.- Changing effort, on most models. On Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 it keeps the cache.
- Turning on fast mode. It has a separate cache. The first time, the whole conversation is read uncached, at fast rates.
- Editing a tool list when tool search is unavailable. With tool search on, which is the default, MCP servers connecting or disconnecting do not disturb it.
And what does not: plugin skills, commands, agents and hooks append after the conversation, so they never invalidate it.
Where caching quietly fails
Two cases are worth knowing because they leave no error.
A gateway that strips the cache_control markers but returns success makes your whole history bill as uncached on every turn. And the cache is effectively tied to one machine and directory, since the system prompt embeds memory paths and the opening message embeds the working directory. Two sessions in the same directory can share a cache.
$ /usage✻ Shows a "Prompt cache (main)" line: hit ratio, misses, warm or cold# Newer versions name a likely cause for a miss.
What a long session really costs
The documented figures are an average, not a promise. Across enterprise users the average is about 13 USD per developer per active day, 150 to 250 USD per month, and 90 percent of users stay under 30 USD a day. Agent teams use roughly seven times the tokens of a standard session when teammates run in plan mode.
Two costs people forget. Thinking tokens bill as output. And some spending happens while you are not typing: session recaps, idle compaction, prompt suggestions (mostly cache reads), scheduled loops and goal check-ins.
You are halfway through a task and want to try fast mode. What is the documented cost?
Chapter complete
You've finished chapter 5 of 6 in Context and memory.
Model, effort and fast mode are three separate dials. Each one changes what a turn costs and how long it takes, and two of them reset the cache if you turn them mid-task.
Next chapter