Prompt Caching Explained for Claude Code and Long AI Sessions

Prompt caching lets the API reuse the unchanged start of your prompt, called the stable prefix, instead of processing it again, and it bills those cached tokens at a fraction of the normal input price. In an AI coding session the prefix is your whole conversation, so a cache read costs about a tenth of fresh input on most Claude models. The first turn after the cache expires pays a premium to write everything again, which is why a long idle break is the expensive part.

What does prompt caching actually cache?

The cache stores a prefix of your request. Anthropic's API builds that prefix in a fixed order: tool definitions first, then the system prompt, then the messages. A hit needs an exact match from the start of the request, so a change anywhere in the prefix forces everything after it to be processed again. There is no per-file or per-paragraph caching.

Claude Code orders every request so that the parts that change least come first:

Layer	Content	Changes when
System prompt	Core instructions, tool definitions	The set of loaded tool definitions changes
Project context	CLAUDE.md, auto memory, unscoped rules	The session starts, or after /clear or /compact
Conversation	Your messages, replies, tool results	Every turn

Each new turn is appended at the end, so most of every request is identical to the one before it. That is the case caching is built for. Through the API you opt in with a cache_control field. One top-level field turns on automatic caching, and you can also place explicit breakpoints on individual blocks, up to four per request.

"cache_control": {"type": "ephemeral"}

Prompts shorter than a model-specific minimum are never cached, and no error is returned. On current Claude models that minimum ranges from 512 to 4,096 tokens, so look up your model in Anthropic's prompt caching docs before you wonder why nothing is being cached.

How much do cache reads and writes cost?

Caching changes the price of the prefix in three ways. Each price is a multiplier on the model's base input price.

Operation	Multiplier	Lifetime
5-minute cache write	1.25x base input	5 minutes
1-hour cache write	2x base input	1 hour
Cache read (hit)	0.1x base input on most models	Same as the write that created it

A few newer models read for less. Anthropic lists 0.05x for Claude Opus 5.5 and 0.025x for Claude Fable 5.1 and Mythos 5.1. The same page gives the break-even: a 5-minute write pays for itself after one read, and a 1-hour write after two reads. Prices change, so check Anthropic's pricing page for your model before you budget. In short, Anthropic cache pricing is three multipliers and a lifetime.

How long does the prompt cache last?

The prompt cache TTL (time to live) is 5 minutes by default, with a 1-hour option that you request with "ttl": "1h" inside the cache_control block. Every request that hits the cache refreshes the timer at no extra cost, so a session stays warm for as long as you keep working. After a gap longer than the TTL, the entry is gone.

Claude Code's own prompt caching page documents how it picks the TTL for you:

• On a Claude subscription, within your plan's included usage, the main conversation gets 1 hour.
• On an API key, a cloud provider, or once a subscription spills into usage credits, the main conversation gets 5 minutes.
• Subagents, compaction and other helper requests default to 5 minutes, with a few server-controlled exceptions on subscriptions.

You can set the main conversation's TTL yourself with the CLAUDE_CODE_PROMPT_CACHE_TTL environment variable or the promptCacheTtl setting. Both accept 5m or 1h and need Claude Code v2.1.242 or later. To see which TTL your writes really used, run this and read usage.cache_creation in the JSON:

claude -p "hello" --output-format json

One-hour writes appear under ephemeral_1h_input_tokens, five-minute writes under ephemeral_5m_input_tokens. The longer TTL costs more per write, so it pays off when you leave sessions idle and come back, and loses a little on short bursts that never pause for five minutes. Whether a subscription or an API key suits you is a separate question, which we cover in our comparison of the two for coding.

Why does a long break make the next turn expensive?

Claude Code re-sends the full conversation on every turn. While the cache is warm, that costs one read of the whole context. After it expires, the next turn has nothing to read. It processes the full context as new input and writes it back to the cache at 1.25x or 2x the base input price, and it is slower too.

Here is the worked example from the Claude Cache Warm README, at list prices: an 800,000-token context on Claude Opus 5 with a 1-hour cache.

Case	Cost (list-price estimate)
One keep-alive ping (cache read)	about $0.40
Cold return after 90 minutes (cache write)	about $8.00

The arithmetic matches Anthropic's pricing page, which lists Opus 5 at $0.50 per million tokens for cache hits and $10 per million for 1-hour writes. 0.8 million tokens at $0.50 is $0.40, and at $10 it is $8.00. Treat both as estimates. Your real bill depends on the model, your plan and how much of the context was cached, and on a subscription the cost shows up as usage against your limits instead of dollars. The ratio is the useful part. One cold rebuild costs about as much as twenty cache reads.

How do you structure prompts to get more cache hits?

Keep the prefix identical for as long as you can, and put everything that changes at the end.

• Put stable content first: tool definitions, system instructions, reference documents. Put the changing question last.
• Never edit earlier content. A timestamp or request ID at the top of a system prompt breaks the match for everything behind it.
• Keep tool definitions stable. In Claude Code, adding or removing a tool definition in the request invalidates the cache, for example when an MCP server connects and its tools load upfront.
• Choose the model and effort level at the start. Each model has its own cache, so a /model switch mid-task makes the next request read the whole history uncached. On most models, changing the effort level does the same.
• Run /compact at natural breaks between tasks. Compaction replaces the history, so it rebuilds the cache by design.
• Avoid turning on fast mode deep into a long session, because its request header is part of the cache key.
• Expect one slow turn after upgrading Claude Code, which usually changes the system prompt.

To measure the result, read the two usage fields the API returns on every response. cache_creation_input_tokens counts tokens written to the cache, and cache_read_input_tokens counts tokens served from it. A high read-to-creation ratio means caching works. In Claude Code, /usage shows a Prompt cache (main) line with the share of input tokens served from cache and whether the cache is warm right now (Claude Code v2.1.251 or later). For products built on the API, the same habits are one layer of the savings in how we cut LLM costs by 99%, where provider prompt caching sits next to exact-match caching and routing.

When do keep-alive pings make sense, and when do they waste quota?

A keep-alive ping is a tiny turn sent before the TTL runs out. It is a real model turn: the API reads the full cached context, which resets the timer. It costs a cache read plus a few output tokens, and on a subscription it counts against your usage limits. Whether it pays depends on the TTL and on how long you will be away.

Situation	Ping?	Why
Large context, 1-hour TTL, waiting on a subagent or build you will certainly check	Yes	One read at about 0.1x replaces a rewrite at 2x
Small context (Cache Warm skips anything under 20,000 tokens by default)	No	Rebuilding a small context is cheap
5-minute TTL and a break of an hour or more	Usually no	About 11 pings at 4-minute spacing already cost as much as one 1.25x rewrite
You may not come back today	No	On a 1-hour cache, pings stop paying after about 19 of them, roughly 16 hours
The cache already expired, for example the laptop slept	No	The ping would be the expensive rewrite

The break-even figures come from the Cache Warm README and assume the standard 0.1x read price. On models with cheaper reads they move later. Two practical rules follow. First, get the 1-hour TTL before you automate anything, because it turns about fifteen pings an hour into one. Second, ping only sessions you are sure to resume. Check Anthropic's current terms and plan rules before you run any automation against a subscription: pings are ordinary turns, but they spend your allowance.

How does Claude Cache Warm automate keep-alive?

Claude Cache Warm is a Claude Code plugin, MIT licensed, that sends the pings for you. Install it from inside Claude Code with the two commands from its GitHub repository:

/plugin marketplace add FiredMosquito831/claude-cache-warm
/plugin install cache-warm@claude-cache-warm

Start a new session and warming is on. By default it warms only sessions that are waiting on a subagent or a background task, because those are the ones you are certain to return to. The ping travels through the live session itself, so it hits exactly the same prefix: same system prompt, same tools, same history. An external claude -p --resume call or a raw API request cannot guarantee that.

The timer counts from your last real request, so a session you are using is never pinged. The plugin also skips a ping when the cache has already expired, when you have been away longer than the idle cap (180 minutes by default), when the context is under 20,000 tokens, or when warming is switched off.

ccw status              # sessions, next-ping countdown, cost per ping
ccw interval 30         # ping every 30 minutes, or auto
ccw when always         # warm any idle session, not only ones with background work
ccw dashboard           # opens http://127.0.0.1:4777/

The auto interval is 50 minutes on a 1-hour cache and 4 minutes on a 5-minute cache, detected from the transcript. The local dashboard shows hit ratio, cold rebuilds and what warming would have saved, all mined from your own transcripts, so keep them around: see our guide to Claude Code session history. Know the limits. Plugin monitors are an experimental Claude Code feature that only runs in interactive CLI sessions, so the plugin falls back to an in-session scheduled task when no monitor is running. Every ping adds two short messages to the transcript. Dollar figures use list prices and are estimates. Model switches and /compact invalidate the cache no matter what a plugin does.

Where does this fit in the work Danube Labs does?

Danube Labs is a founder-led software and AI studio in Bucharest, and it built Claude Cache Warm and released it as open source. The same prefix discipline applies to any product built on an LLM API, where it is among the cheapest savings available. If you want a second pair of eyes on where your LLM spend goes, see our AI systems work or book a free intro call.