How Claude's prompt cache works

From zero: what Claude Code sends on every message, what Anthropic keeps in its cache, what that costs, when it expires, and what keep-warm, /rewind, /branch, /fork, subagents, /model and /compact do to it. Then: how to build the same things in your own harness on the Anthropic API.

1. Words this page uses

Each word below means one thing on this whole page. Skim it now and come back when a word is unclear.

2. Why a cache exists at all

2.1 Claude remembers nothing between requests

Every API request stands alone: the model keeps no memory of the previous one. So to continue a conversation, Claude Code sends the whole conversation again, every time, with the new part added at the end.

Each time, the request carries everything from before plus the newest part (white outline). In a long session that is hundreds of thousands of tokens per request.

2.2 What is inside one request

A request is a list of blocks, always in this order. The order matters (rule 1).

2.3 Why that would be slow and expensive

Before the model can answer, it must process every input token. Without a cache, a 200,000-token conversation means processing 200,000 tokens on every message, although 99% of them are the same as last time. Prompt caching lets the API skip the part it processed recently, and bill that part at a tenth of the normal price or less.

3. The rules of the cache, one at a time

Rule 1. Entries are found by the exact start of the request

An entry is found again only when a later request starts with exactly the same blocks, in the same order, byte for byte, sent to the same model. One changed character in SYS, and nothing after it can match. That is why the blocks that change least come first.

Rule 2. A cache breakpoint 🚩 says where an entry ends

The request marks the blocks after which the API should store an entry (up to 4 marks per request). Claude Code places them for you: one at the end of the latest message on every request, and others earlier, such as after the system prompt. Claude Code's docs don't list where every 🚩 goes, so this page simplifies: it draws two per request, after SYS and after the last block.

Rule 3. Every request is split into four kinds of tokens

When a request arrives, the API looks for the longest prefix that ends where a live entry ends (it searches back from each 🚩, up to 20 blocks). Then every token falls into one of these:

On a Max plan you don't pay per token inside your plan's usage. We assume the same ratios decide how fast that usage runs out; Anthropic's docs don't say. inferred

Rule 4. A reply is not cached when it is written

The cache stores only what was sent in. A reply is output, so at first it exists only on your machine. It enters the cache on the next request, when Claude Code sends it back before that request's 🚩.

Rule 5. Entries expire; every read restarts the timer

An entry lives for its TTL after its last use. The timer starts when that request starts, not when its reply ends. Each request that reads through it restarts the timer, for free. If nothing reads it for the whole TTL, it is deleted, and the next request processes and writes everything again: the slow, expensive turn. Claude Code asks for 1 hour for your main conversation on a subscription (within its usage) and 5 minutes for side requests. With an API key, usage credits or a cloud provider, it asks for 5 minutes for both, unless you set promptCacheTtl. Below, one hour runs in 6 seconds: green ticks are requests reading the entry; then you stop.

4. Step through it: pick a scenario

Each card is one situation, written as the question it answers. Pick one, then press Next (or click the progress bar). Every step animates in order: the clock moves, the request is assembled, the API matches it against the cache, the usage comes out, the cache updates, and your conversations update.

A model built from the rules above. Token sizes are made up but realistic. Block widths are not to scale. The 20-block search limit is left out; it never matters here. The cost line uses the standard prices: read 0.1×, write 2× for a 1-hour entry or 1.25× for a 5-minute one. On Opus 5.5 and Sonnet 5.5 a read costs 0.05×.

5. Reading the numbers Claude Code shows you

Every response reports the four counts from rule 3. The context-meter mod adds them up per message:

◆ ctx 7% · sent 214k in 3 requests (99% cached) · out 1.4k · $0.0270

A cache bust (counted at the right of the status line) is a request that read nothing. A subagent's first request usually counts as one: it starts its own conversation with a different SYS, so it can't read your entries (scenario "A normal subagent").

6. The keep-warm ping, in detail

After 50 idle minutes the keep-warm mod calls $.model.fork. Claude Code's mod API types describe it as: the main conversation's last request again (same model, system prompt, tools, messages) with one extra message after it, and "its own tail never cached". Scenario "Away 61 minutes, with keep-warm" animates it.

1. Everything up to message 2 is identical to your last request, so it is a cache read, and that read restarts the timers of the entries along that chain.
2. The ping is processed but not stored.
3. "pong" is output, never stored, and the mod discards it. Your conversation does not change.
4. Your next real request starts exactly like the entry the ping refreshed, so it matches.

Is "ping / pong" anything special?

No. "Reply pong" is just a short message I chose; any tiny message works. Nothing in the API knows about pings. What makes it work is ordinary prompt caching:

• the request starts with exactly your last request: same model, same system prompt, same tools in the same order, same messages;
• it is sent before the entry expires;
• it adds as little as possible after the match and asks for a tiny answer, so it costs about one cache read.

So yes, you can do the same in your own projects with the plain Messages API. Part 8 has the code. The ping is a side request with a 5-minute TTL, but that doesn't shorten your entry: while your entry is warm, the ping writes nothing, and in our test the session was still fully cached 11 minutes after the ping.

7. Sessions, rewind, branch and fork, from the API's point of view

7.1 The API has no sessions

The Messages API takes a model, a system prompt, tools, a list of messages and a max-tokens limit, and returns one response. It keeps no conversation on its side. The only thing it keeps is the prompt cache, and the cache is keyed by content and model, not by session, user or branch (it is shared within one workspace on the Claude API, and within one organization on Amazon Bedrock and Google Cloud).

So every Claude Code feature below is the same move underneath: Claude Code decides which list of messages to send next. The cache simply rewards lists that start the same way as a recent one.

7.2 Branch vs fork vs subtask

At the API level all three are the same: a request whose messages start like yours. The differences are what Claude Code does around it: which list keeps growing, which session you are in, where files get edited, and what comes back.

7.3 Edge cases with fork, branch and rewind

8. Build it yourself on the Anthropic API

Everything in part 7 can be built in your own harness, because none of it is a server feature. Sessions, rewind, branch, fork, subtasks, subagents, compaction and keep-warm are all "decide which messages to send". The cache does the rest, if you follow these rules:

A sketch in Python with the official SDK. Not run: it shows the shape, check names against the current API docs.

# pip install anthropic
import copy, anthropic

client = anthropic.Anthropic()
MODEL = "claude-opus-5-5"
TTL = {"type": "ephemeral", "ttl": "1h"}
SYSTEM = [{"type": "text", "text": open("system.md").read(), "cache_control": TTL}]   # 🚩 after SYS
TOOLS = [...]                       # same list, same order, every request

def with_flag(messages):
    """A copy of the list with a 🚩 on its very last block."""
    msgs = copy.deepcopy(messages)
    last = msgs[-1]
    if isinstance(last["content"], str):
        last["content"] = [{"type": "text", "text": last["content"]}]
    last["content"][-1]["cache_control"] = TTL
    return msgs

def send(session, text):
    """A normal turn: append, send everything, append the reply.
    No tool loop here: a tool_use reply needs tool_result blocks in the next message."""
    session.append({"role": "user", "content": text})
    r = client.messages.create(model=MODEL, max_tokens=4096, system=SYSTEM,
                               tools=TOOLS, messages=with_flag(session))
    session.append({"role": "assistant", "content": r.content})
    print(r.usage)                  # cache_read_input_tokens, cache_creation_input_tokens, input_tokens
    return r

def rewind(session, index):
    """/rewind: drop everything from this user message on. Pick an index of a real
    user prompt, not a tool result, so roles stay valid."""
    del session[index:]

def branch(session):
    """/branch or /fork: an independent copy. Its first request reads the original's cache."""
    return copy.deepcopy(session)

def subtask(session, brief):
    """/subtask: a side run on a copy; only its answer comes back.
    Put the answer into your next message in the main session."""
    side = branch(session)
    return send(side, brief).content[-1].text

def keep_warm(session):
    """Keep-warm: your last request again, with max_tokens=0, so no reply. Nothing is kept."""
    msgs = with_flag(session[:-1])  # the last request exactly: everything before the last reply
    r = client.messages.create(model=MODEL, max_tokens=0, system=SYSTEM,
                               tools=TOOLS, messages=msgs)
    return r.usage.cache_read_input_tokens   # about the whole conversation if it worked

def compact(session):
    """/compact: ask for a summary over the cached list, then start a new list from it."""
    side = branch(session)
    summary = send(side, "Summarize this conversation so work can continue.").content[-1].text
    session[:] = [{"role": "user", "content": "Summary of our work so far:\n" + summary},
                  {"role": "assistant", "content": "Understood."}]

On the plain API you need no ping. max_tokens=0 is the API's documented pre-warming mode: it reads the prompt into the cache and returns no output, so no output tokens are billed. It is refused with streaming, extended thinking, structured outputs or a forced tool_choice. Claude Code's $.model.fork has no such option, which is why keep-warm sends a ping. Run keep_warm on a timer a few minutes before the TTL runs out, and stop after a few rounds if nobody comes back.

9. What resets the cache, and what doesn't

Anything that changes an early block changes the start of every later request. From Claude Code's prompt-caching docs:

10. What we measured

In the browser terminal on 2026-10-14, with Claude Haiku 5.5 sessions:

The session without a ping still got 24%: most likely its SYS stayed warm because the other test sessions in the same folder sent the same SYS (Claude Code's docs say sessions run in parallel in the same directory read each other's cache, and sequential ones do when their startup git status matches). Not tested.

11. Where each fact comes from