Prompt caching in Claude Code, explained simply

Claude Code sends the whole conversation on every request. Prompt caching lets Anthropic's API skip the part that matches what it processed last time, from the system prompt down, and bill it at the cache-read price: $0.20 per million tokens on Opus 5.5, against $4 for normal input. The cache stays warm for five minutes or an hour after its last use. /model, a changed tool list or a long break makes it go cold.

How prompt caching works in Claude Code#

The model remembers nothing between requests. So every time you send a message, and every time Claude uses a tool, Claude Code sends everything again: its system prompt, your project context, every message and tool result so far, and the new bit at the end.

Most of that is identical to the previous request. The API matches the start of each request, called the prefix, against what it processed recently. Anthropic's prompt caching page is precise about the rule: "The match is exact, so a change anywhere in the prefix recomputes everything after it. There is no per-file or per-segment caching."

That's why Claude Code puts what rarely changes first:

A new turn only adds to the bottom layer, so everything above it is read from cache. A change to the top layer invalidates everything below it.

What caching saves: reads, writes and misses#

The API reports cached tokens in two fields on every response, and they are billed differently. cache_creation_input_tokens is the prefix written on this turn, at a little more than normal input. cache_read_input_tokens is the part served from cache, at a small fraction of it. Anthropic's API pricing on 22 October 2026, in US dollars per million tokens:

$0.20 against $4 makes a cache read 1/20 of normal input on Opus 5.5, and $0.25 against $10 makes it 1/40 on Fable 5.1. Pro and Max plans don't bill per token, but the reads still count toward your limits. Anthropic's cost guide shows it with a session left open all day: a one-line question there "still draws usage for the whole conversation."

How long the cache lasts#

The clock restarts on every request that reads the cache, so the TTL is the longest gap a chat can take and still find it warm. Its length depends on how Claude Code is signed in (Claude Code docs, 22 October 2026):

Past your plan's limit, on usage credits, Claude Code drops the main conversation to five minutes, because those writes are billed. Three settings override the default:

To see which one your writes used, run claude -p "hello" --output-format json and read usage.cache_creation: one-hour writes are counted under ephemeral_1h_input_tokens, five-minute ones under ephemeral_5m_input_tokens.

What breaks the cache#

Each of these makes the next request miss some or all of the cache. That one turn is slower and pays the write price, and the turn after it reads the new prefix from cache.

• /model to another model. Caches are per model, and opusplan runs Opus in plan mode and Sonnet outside it, so every plan-mode toggle is a model switch.
• A new effort level, on most models. On Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 the cache now survives it, with an API key or a subscription.
• Fast mode, the first time you turn it on in a conversation.
• MCP tools added or removed, but only when tools load upfront. With tool search, the default on supported models, a server connecting mid-session leaves the cache alone.
• /compact, which replaces the history with a summary by design.
• Many images. When a request would pass the image limits, Claude Code drops a batch of the oldest, and the history changes from that point on.
• A Claude Code upgrade. The first session after it builds its cache from the top.
• A gap longer than the TTL. Nothing is left to read.

What doesn't break it#

Anthropic's page lists these as cache-safe:

• Editing CLAUDE.md mid-session. It was read once at the start and held. The edit doesn't break the cache, but it also doesn't apply until /clear, /compact or a restart.
• Editing files in your repo, changing permission mode or output style, running skills and commands, /recap, /rewind, and starting a subagent.

After a wrong turn, /rewind returns to a prefix that's already cached, while /compact builds a new one and pays the write price for it.

Why an idle chat costs more when you come back#

Past the TTL, the next message finds nothing to read, and the whole conversation goes in again as a cache write. The arithmetic for a 200,000-token conversation on Opus 5.5, at API list prices:

That's 25 to 40 times the price for the same message, only because of the pause. And a turn is often several requests, though only the first one after the break pays the cold price. Anthropic doesn't publish how cache tokens weigh against subscription limits, so we won't put a number on that; the direction is the same.

/usage shows your own numbers. Since v2.1.251 it has a Prompt cache (main) line with your hit rate, misses and whether the cache is warm now, and since v2.1.260 it names the likely cause of the last miss, for example likely cause: tool definitions changed.

Does moving a chat to another account start a cold cache?#

Yes. Anthropic's API docs say: "Caches are isolated between organizations. Different organizations never share caches, even if they use identical prompts." Each personal Pro or Max account is its own organisation, so the first request after the move re-reads the whole conversation at the cache-write price. Anthropic doesn't say whether two seats in one Team organisation share a cache in Claude Code, so we plan for a cold start there too.

The same goes for moving a chat to another computer. Claude Code's docs say the cache is "effectively scoped to one machine and directory", because the prompt names your working directory, platform and auto-memory path.

So a move costs one cold turn: for the 200,000-token Opus 5.5 chat above, $1.00 or $1.60 at list price instead of $0.04. When the old account is out of its limit, the other choice is a chat that stops for three hours, and one cold turn is the better deal. When both accounts have room, moving back and forth only burns the cache.

How Shuriken handles the cache#

Every hot swap pays this cost once. Hot swapping is Shuriken moving your chats to another of your accounts or sources when one nears its limit: the chat continues, and its first turn on the new account writes the cache from scratch. We'd rather say that plainly than pretend a move is free.

• A chat stays on the source it moved to while that source is still among the best choices. It doesn't trade back and forth between two accounts with room every time a usage reading changes (how switching picks the next account has the ranking).
• A 529 overload is retried on the same account before any move, because one busy minute isn't worth a cold cache.
• By default a chat stays on one source until it reaches your switch point (99% by default). Spread the work (our Distribute mode) moves chats to the source with the most left, every 15 to 60 minutes when another source is at least 5 points better, and each of those moves starts a cold cache. That's a fair trade when you want limits to drain evenly, but know what it costs.
• The context popup over a chat's composer shows the cache: "Warm while it works" during a turn, then "Warm · 42m left" with how many tokens the next message would re-read from it.

Use only accounts you own and are entitled to use: providers' terms may not allow sharing a subscription sign-in. For the bigger picture of where tokens go, read why Claude Code uses so many tokens.

If you'd like to watch your cache and your accounts in one place, download Shuriken.