12 / 20Performance7 MIN READ

Prompt Caching

Prompt caching lets the API reuse the already-processed start of a request, so Claude Code only pays full price for the part of the conversation that changed since the last turn.

What it is

Every turn is a new API request carrying the entire context: system prompt, project context, all prior messages and tool results, plus your new message. The API matches the start of each request — the prefix — against content it recently processed, reads the match from cache, and fully processes only what follows. The match is exact and positional. There is no per-file or per-segment caching: a change anywhere in the prefix recomputes everything after it.

Claude Code orders each request so the stable content comes first. The system prompt layer holds core instructions, tool definitions, and the output style, and changes when the loaded tool set changes or Claude Code is upgraded. The project context layer holds CLAUDE.md, auto memory, and unscoped rules, and changes on session start, /clear, and /compact. The conversation layer changes every turn. A change in the conversation layer leaves the two above it cached; a change to the system prompt invalidates everything.

Two things outside the prompt text are also part of the cache key: the model and the effort level. Each has its own cache, so switching either recomputes the whole request even though the content is identical. Claude Code shows a confirmation dialog before an effort change that would invalidate the cache.

What it does for you

It makes long sessions affordable. Cache reads bill at roughly ten percent of the standard input rate, so a fifty-turn conversation does not cost fifty times the first turn.
It explains the slow turns. A model switch, a plugin toggle, or an MCP server dropping mid-session is followed by one uncached turn that reprocesses everything.
It is why several settings wait for a restart. Editing CLAUDE.md or changing the output style mid-session would break the prefix, so Claude Code keeps using the version loaded at session start and applies the new one on /clear or restart.

How it works

01The request is assembled stable-first
System prompt, then project context, then conversation. New content is appended at the end, so most of each request is byte-identical to the one before it.
02The API matches the longest identical prefix
Matched tokens are read from cache and billed at the cache-read rate. Everything after the first difference is processed and written to cache for next time.
03Model and effort are part of the cache key
Each model has its own cache; each effort level has its own cache within a model. Switching either means the next request reads the whole history with no cache hits.
04Deferred tool definitions sit outside the cached prefix
With tool search enabled — the default on supported models — an MCP server connecting or disconnecting only appends content. When tool definitions load into the prefix instead, any change to them invalidates the cache.
05The cache expires after a period of inactivity
Each hit resets the timer. On a Claude subscription Claude Code requests the one-hour TTL automatically; on an API key or third-party provider it uses five minutes unless you set ENABLE_PROMPT_CACHING_1H=1.
06The cache is scoped to a machine and directory
The system prompt embeds the working directory, platform, shell, OS version, and auto-memory paths, so two sessions in different directories — including two worktrees of one repository — build different prefixes.

How to implement it

01Pick your model and effort level before you start working
Both are cache keys. Choosing them at the top of a session costs nothing; changing them forty turns in reprocesses forty turns.
02Watch the two token counts
The API reports cache_creation_input_tokens and cache_read_input_tokens on every response. A statusline script that reads the current_usage object is the most direct way to see them live.
03Interpret a persistently high creation count
Read-to-creation should be high after the first turn. Creation staying high turn after turn means something in your prefix keeps changing — usually an MCP server reconnecting, a plugin toggling, or repeated model switches.
04Move cache-breaking changes to session boundaries
Enable fast mode, switch models, toggle plugins, and change deny rules at the start of a session or right after a /clear, where the cache is being rebuilt anyway.
05Prefer rewind over compact when abandoning work
/rewind truncates back to a prefix that is already cached and stays warm because every turn since read through it. /compact builds a new, shorter prefix from scratch.

Examples

What breaks the cache and what does notbash

# Invalidates the cache — one slow, expensive turn follows
/model opus                 # each model has its own cache
/effort max                 # each effort level has its own cache
/fast on                    # adds a header that is part of the cache key
/compact                    # replaces history with a new, shorter prefix
# an MCP server connecting or disconnecting, when tools load upfront
# enabling or disabling a plugin that provides an MCP server
# adding a bare deny rule such as "Bash" or "WebFetch"
# upgrading Claude Code, or resuming a session after an upgrade

# Keeps the cache — appended after the existing prefix
/plan                       # plan mode appends instructions as messages
/skill-name                 # skills and commands inject at the end
/recap                      # appends a summary as command output
/rewind                     # truncates back to an already-cached prefix
Shift+Tab                   # permission mode changes are cache-safe
# editing a file Claude already read (a system-reminder is appended)
# editing CLAUDE.md mid-session (no effect until /clear or restart)
# spawning a subagent (its calls append; it builds its own cache)

Left column costs you one full reprocess of the conversation. Right column costs nothing.

.claude/settings.jsonjson

{
  "statusLine": {
    "type": "command",
    "command": "jq -r '\"cache read \" + (.current_usage.cache_read_input_tokens // 0 | tostring) + \" · written \" + (.current_usage.cache_creation_input_tokens // 0 | tostring)'"
  },
  "env": {
    "ENABLE_PROMPT_CACHING_1H": "1"
  }
}

A statusline that surfaces the two numbers that tell you whether caching is working.

Use it when

Diagnosing why one turn in a long session was suddenly slow and expensive.
Deciding when to switch models: at the start of a task rather than in the middle of one.
Explaining why an edit to CLAUDE.md had no effect until the next /clear.
Choosing /rewind over /compact to abandon a dead end without rebuilding the prefix.
Keeping the cache warm across longer breaks with ENABLE_PROMPT_CACHING_1H=1 on an API key.

Avoid it when

You are debugging caching behaviour itself. DISABLE_PROMPT_CACHING=1 and the per-model variants exist for exactly that, and only that.
You would contort the work to protect the cache. One uncached turn is cheaper than staying on the wrong model for an hour.
You are running short one-shot -p invocations. There is no second turn to hit the cache, so the ordering rules do not buy you anything.
Your requests go through a gateway that rejects cache breakpoints. Claude Code retries without the breakpoint and leaves that block uncached for the rest of the conversation.

Common mistakes

SYMPTOMSwitching models mid-task and being surprised by the slow turn that follows.
FIXEach model has its own cache, so the next request reads the entire history uncached. Switch at the start of a task, or right after /clear.
SYMPTOMEditing CLAUDE.md during a session and wondering why nothing changed.
FIXProject-root and user CLAUDE.md are read once at session start and held in memory. The edit does not invalidate the cache and it does not apply. Run /clear, /compact, or restart.
SYMPTOMAdding a bare Bash deny rule and getting a full reprocess on the next turn.
FIXA bare tool name removes the tool definition from the system prompt layer. Use a scoped rule like Bash(rm *), which Claude Code checks at call time and which leaves the prefix intact.
SYMPTOMCache creation stays high every turn and nobody knows why.
FIXSomething in the prefix keeps changing. The usual causes are a stdio MCP server whose process keeps exiting, a plugin toggling, or repeated /model switches. Run /mcp to check connection stability.
SYMPTOMResuming a long session after an upgrade and paying the most expensive request of the week.
FIXA new Claude Code version usually changes the system prompt, so the whole history sits behind a different prefix. Start new work in a new session rather than resuming a very long one after upgrading.

Best practices

Choose the model and effort level at the top of a session and leave them alone.
Save /compact for natural breaks between tasks rather than letting it fire mid-task.
Reach for /rewind rather than /compact when abandoning a path — it lands on a prefix that is already cached.
Scope deny rules rather than denying whole tools, so tool definitions stay stable.
Watch cache_read_input_tokens against cache_creation_input_tokens and treat a high creation rate as a symptom to investigate.
Remember two worktrees of the same repository do not share a cache, because the working directory is embedded in the system prompt.

Try it in five minutes

Watch a model switch destroy the cache, in your own status line.

1.Add the statusline command from the example above to ~/.claude/settings.json and restart Claude Code.
2.Ask three or four questions in a row and watch cache read climb while written stays small.
3.Run /model and switch to a different model.
4.Ask one more question: cache read drops to zero and written jumps to the size of the whole conversation.
5.Ask another question and watch the read count recover, now against the new model’s cache.

Verified against code.claude.com/docs/en/prompt-caching on 2026-08-09. See content/SOURCES.md for the full table.

← / → MOVE BETWEEN CONCEPTS