Claude Prompt Caching Runs on a Clock, Not a Budget

Claude prompt caching is time based. In Claude Code, the cached copy of your conversation expires on a timer, every request you send resets that timer, and once it runs out the next message reprocesses the whole history at full price. Work in short bursts and the cache never goes cold. Step away for an hour and the first message back pays for everything.

Caching reads like a size problem. It is a timing problem, and the timer runs when you stop working.

If you want the short version, jump to the 3 habits.

Key Takeaways

Claude prompt caching expires on a timer: about 1 hour on a plan within usage limits, about 5 minutes on API or cloud, 5 minutes for subagents everywhere.

Every request resets that timer. The cache goes cold because you stopped working, not because the session got long.

Run /usage to see what share of your input came from cache. It should be high.

A one hour window is billed at a higher write rate, so short bursts are usually cheaper on the short window. Only lengthen it if you actually step away and return.

/compact is cheap while the cache is warm and full price on a resumed session. Run it before you step away.

Switching models, changing effort, or adding an MCP server all rewrite the front of the request and invalidate everything after it.

Editing files, changing permission mode, and editing CLAUDE.md mid session are all free. CLAUDE.md is only read at session start.

Fable 5.1 is the one model where changing effort keeps the cache.

What is Claude prompt caching?

One prompt is many requests, and every request carries the entire conversation. Your system prompt, your tool definitions, your CLAUDE.md, every message and tool result so far, all of it goes back to the model on every single turn.

The part at the front that is identical to the previous request is called the prefix, and that is what gets cached. It is read back for a small fraction of the normal input price. New material pays full price once, and from the next request on it is inside the cached prefix too.

Claude Code sets all of this up for you. You do not turn it on. What you control is whether you keep breaking it.

This is the biggest lever you have, because nearly everything that goes into a request is prefix. In a healthy session, most of your input is the cheap cached kind.

How do I check if my cache is actually working?

Run /usage. There is a line for the prompt cache, and it shows exactly how much of your input came from cache.

In a healthy session that number should be high. There is no published floor to measure yourself against, so read it as a trend rather than a score: check it early in a session and again after an hour of work. A drop is the signal. If it is low, you are breaking the cache somewhere, and the sections below are the list of ways that happens.

The companion command is /context, run in a fresh session. It shows what you are actually sending before you send anything: system prompt, loaded tools, your CLAUDE.md, your skills, your MCP servers, with token counts against each. Worth a look before you start something long, if only to find the thing you forgot you had loaded.

How long does the cache last, and what resets it?

How long is the window?

It depends on where you are running, and the gap is large. These are the numbers today, and they are the kind of thing that moves.

Where	Cache lifetime
Claude Code on a plan, within your plan's usage	About 1 hour
API billing or a cloud provider	About 5 minutes
Subagents, everywhere	5 minutes

Subagents are the exception worth remembering. They get 5 minutes regardless of what your main session is set to.

Does using the cache reset the timer?

Yes, and this is the whole trick. The server keeps the prefix around for a limited time, and every request you send resets that timer. While you are working, the cache stays warm.

So the cache does not expire because your session got long. It expires because you stopped.

That inverts the usual instinct. A 4 hour session where you send a message every few minutes stays warm the entire time. A 20 minute session with a 90 minute lunch in the middle goes cold once, and the message after lunch costs more than any message in the 4 hour one.

Two timelines compared. In the top one, labelled Short bursts, evenly spaced requests keep an unbroken warm band running the full length. In the bottom one, labelled One long gap, the warm band stops partway through where the cache expires, and the requests after the gap are marked full reprocess.

Should I set the cache window to an hour?

Not automatically, and this is the part that gets skipped.

There is a promptCacheTtl setting for the main conversation and a matching subagentPromptCacheTtl for subagents, in ~/.claude/settings.json alongside the rest of your settings, or in managed settings for a whole team:

{
  "promptCacheTtl": "1h",
  "subagentPromptCacheTtl": "1h"
}

But the long window is not free. Writing tokens into a 1 hour cache is billed at a higher rate than writing them into a 5 minute one. So if you work in steady bursts and rarely pause for more than a few minutes, the short window is usually cheaper, because you would be paying extra for time you never use.

The long window pays off when you genuinely do step away and come back to the same session. A meeting, a lunch, a long build. Match the setting to how you actually work, not to the bigger number.

On a subscription plan you are working against usage limits rather than a per token bill, so the practical cost of a cold cache is limit consumed rather than dollars charged.

What breaks the prompt cache?

Expiry is one way to lose the cache. Changing the front of the request is the other.

The server can only reuse the part of the request that is identical to the previous one, starting from the very first token. The moment one token differs, everything after that point is new and gets processed at full price.

A request drawn as a horizontal bar. The left portion is a solid block labelled cached prefix with a CACHED badge, the right portion is segmented and labelled new input. Below it, the same bar with a single small edit marked near the left end, and everything to the right of that edit drawn as an empty outline, labelled everything after is discarded.

That prefix contains more than your conversation:

In the prefix	Which means
Tool definitions	Adding or removing an MCP server rewrites the front
System prompt	Includes your working directory and a snapshot of your git state from session start
Your CLAUDE.md	Read once, at session start
The conversation so far	Everything, in order

So the things that break it are the things that sit in front of your request:

Switching models mid session. The cache is that model's own internal state, so a different model has nothing to reuse and reads your whole conversation fresh once.
Changing effort level, on most models. Effort is how thorough the model is before it calls the job done, set with /effort. More on the exception below.
/compact and /clear. Both rewrite everything leading up to this point, so both break the cache by definition. After a compact that is just a short summary, so it is usually fine.
Adding or removing an MCP server, which changes the tool definitions.

Claude Code usually warns you about the first two. Run /model or /effort while the cache is still warm and it will normally ask you to confirm first.

What is safe to change mid session?

More than you would think, which saves tiptoeing around things that cost nothing.

Editing files is free. So is changing permission mode. Those are Claude Code side and never touch your request.

Editing your CLAUDE.md mid session does nothing at all. It is read once, at session start. Change it now and nothing changes in this session. It shows up in your next one, or after you clear.

The Fable 5.1 exception

Changing effort level normally throws the cache away, because effort sits in front of your request like everything else in the prefix.

Fable 5.1 is the exception. On Fable 5.1, changing effort keeps the cache. It is the only model where that is true.

That makes effort a dial you can turn during a session rather than a decision you are locked into. Drop it for a stretch of mechanical edits, raise it for the hard part, and the conversation history stays cached across both. On any other model, the same move costs you the entire prefix.

Why /compact costs the most on an old session

Compaction means the model reads your entire conversation one more time in order to write the summary. What that read costs depends entirely on whether the cache is warm when you run it.

While the cache is warm, that read comes out of the cache and is cheap. If you wait until after the window closes, say you come back an hour later and then compact, the same read is now full input price.

So compact before you step away, not when you come back. Same command, same summary, and the version you run inside the window is the cheap one.

The same applies to resuming an old session. By then the cache has almost certainly expired, so that first message back sends the whole conversation to the model as plain uncached input. That is fine if you need the full context, and it only happens once. But if you know you are coming back tomorrow, compact before you leave, so what you resume is a short summary rather than everything.

What changed for me once I knew about the window

I did not know the cache was time based until recently. Knowing it has not made me use Claude Code differently so much as made me deliberate about when I do certain things, compaction most of all. It moved from something I ran when the context felt heavy to something I run at a particular moment, which is before I step away rather than after I come back.

The other half is that I mostly do not compact at all. I hand over to a new session instead, and brief it with cross session messaging.

Both moves cost the same in cache terms, which is the thing worth understanding. Compacting and starting fresh each replace the prefix, so either way the warm cache goes. What differs is who decides what survives. Compaction hands that choice to the summarizer. A handover hands it to me, and the new session starts from a small prefix rather than from a summary of something large.

What it does not do is escape the clock. Writing a handover brief is a request like any other, and it reads the conversation to write it. Do that while the cache is warm and it is cheap. Do it after an hour away and you pay full price for the same read, which is the identical trap as a late compact. So the rule holds either way, with one word swapped: hand over before you step away, not when you come back.

Compact before you switch models, not after

If you do need to switch model in the middle of a task, compact first, then switch. The new model has to read your conversation fresh either way, so give it a short summary to read instead of the entire history.

Your context only ever grows

The model only ever adds to your context. It never removes anything. So in a long session, everything from earlier is still there on every request, and even though most of it is cached, cache is not zero.

Run 3 tasks in one long session and task 3 is still carrying task 1 around. Run /clear between them and each task starts small again. In that demonstration the long session used twice the tokens of the cleared one, purely because tasks 2 and 3 dragged task 1 along the whole way. The actual multiple depends on how big your tasks are.

3 tools for this:

/clear when you start something genuinely new.
/compact to replace the conversation with a summary. You can give it hints about what to keep.
/rewind to drop the last few turns.

If you think you will want the old conversation back, rename the session first, then clear. Resume still finds it.

Effort: not knowing versus not trying

Effort tells the model how thorough to be before it calls the job done. Higher effort means more output tokens, which then become more input tokens on every request after.

The default is usually fine. It is tempting to run on the highest setting because you care about the task, but on newer models a lower effort level is sometimes as good as an older model at its highest. On a larger model like Fable 5.1, medium is excellent, whatever the name suggests.

When a result misses, one question sorts it: did it not know enough, or did it not try hard enough? Unfamiliar territory or a subtle bug is a model question. A skipped file, a test never run, a job abandoned halfway, that is effort. It works in the other direction too: if it is doing far more than you asked, turn effort down.

The model sits on top of all of this as a multiplier, since a larger one does more computation on every token in and out.

3 habits that follow from all this

Decide at the start, then leave it. Model, effort and MCP servers all sit at the front of the prompt. Choose them at the beginning of a session or right after you clear, when there is nothing cached to lose.

Be deliberate about what goes in. Point Claude at files you already know it needs by referencing them in the prompt, so that first tool call never happens. Keep CLAUDE.md to what applies to every task and move the rest into skills, which only load when the model decides it needs them. Keep command output quiet, since a test runner that prints one line per passing test leaves all of those lines in every request afterwards. Run /mcp and switch off servers you are not using this session, or reach for a CLI instead, which loads nothing upfront. Send noisy digging into a subagent so only the conclusion comes back.

Do not let one session run forever. Clear when you start a new task. Compact before you step away, while the cache is still warm.

Efficiency here is not about using fewer tokens. It is about the ones you do use going toward the thing you actually asked for.

FAQ

Is Claude Code prompt caching on by default?

Yes. Claude Code sets it up automatically. What you control is the lifetime, through promptCacheTtl and subagentPromptCacheTtl, and whether you keep invalidating it.

No. A subagent runs in its own context with its own cache and its own default five minute window, and it is not free. Its total can even run higher for a single job. What you win is that the reading stays over there and only the conclusion comes back, so every turn in your main conversation afterwards is smaller.

Does /clear break the cache?

Yes, by design. It rewrites everything leading up to this point, so the next request writes a fresh entry. That is the intended behaviour when you are switching tasks, and it is why /clear and /compact are not interchangeable.

Will Claude Code tell me before I break the cache?

Often. Running /model or /effort while the cache is warm prompts you to confirm first.