Prompt Caching Deep Dive

Every turn, Claude Code re-sends the entire conversation to the API. Prompt caching is why that’s fast and affordable: the API matches the unchanged prefix of your request against what it recently processed and only computes the new part. Cache reads cost ~10% of normal input tokens.

How the Request Is Layered

Layer	Contains	Changes when
System prompt	Instructions, tool definitions, output style	Tool set changes, upgrade
Project context	CLAUDE.md, auto memory, rules	Session start, `/clear`, `/compact`
Conversation	Messages, tool results	Every turn (appended at end)

The match is exact-prefix: a change anywhere recomputes everything after it. That’s why stable content is ordered first, and why the model and effort level are part of the cache key (each has its own cache).

What Invalidates the Cache (one slow, expensive turn)

/model switch — including every opusplan plan-mode toggle, and Fable’s automatic safety fallback
/effort change — Claude Code asks for confirmation first
Turning on /fast the first time in a conversation (cache-missed tokens billed at fast-mode rates — enable early, not deep into a session)
MCP server connect/disconnect — but only when its tools load into the prefix; deferred tools (the default) don’t invalidate
Plugin enable/disable — only if it ships MCP servers; skills/hooks/commands never invalidate
Denying an entire tool (Bash bare deny rule) — removes it from the system prompt. Scoped rules like Bash(rm *) are cache-safe
/compact — by design (new shorter history); the summarization call itself reads the old cache, so it’s cheaper than it looks
Upgrading Claude Code — new system prompt; resuming a long session after an upgrade is the most expensive single turn you can send

What Keeps the Cache

Editing repo files (Claude just re-reads; a system-reminder is appended)
Editing CLAUDE.md mid-session — cache-safe because it doesn’t apply until /clear/restart (common confusion!)
Changing output style (same: applies next session)
Switching permission modes (except opusplan’s model flip)
Invoking skills/commands, /recap, spawning subagents
/rewind — truncates back to an already-cached prefix; cheaper than /compact when abandoning a path
Toggling /advisor

Cache Lifetime (TTL)

Subscription: 1-hour TTL automatic (drops to 5 min when drawing on usage credits)
API key / Bedrock / Vertex: 5 minutes default; ENABLE_PROMPT_CACHING_1H=1 opts in to 1h (higher write rate)
Every cache hit resets the timer. The first turn after a long break re-reads everything — that’s the slow “welcome back” turn.

Scope: effectively per machine + directory (the system prompt embeds cwd, platform, git status). Parallel sessions in the same directory share cache; worktrees don’t.

Check Your Hit Rate

Two fields on every API response (readable from a statusline script):

Field	Meaning
`cache_read_input_tokens`	Served from cache (~10% price)
`cache_creation_input_tokens`	Written to cache (slightly above normal price)

High read : creation ratio = healthy. Creation staying high every turn = something is churning your prefix — check the invalidation list above.

The Pro Habits

Pick model + effort at the top of a session; don’t flip mid-task
/compact at natural task boundaries, never mid-flow; prefer /rewind to abandon a path
Enable fast mode early if you’ll want it at all
Keep MCP tool search on (deferred tools) — ENABLE_TOOL_SEARCH=auto
After upgrading Claude Code, start fresh rather than resuming a giant session
Debugging: DISABLE_PROMPT_CACHING=1 exists; FORCE_PROMPT_CACHING_5M=1 forces the short TTL

🧠 Quick Recall

Trick: “Exact prefix match — and model + effort are part of the key.”
Health metric: cache read : creation ratio.

👨‍🏫 Teach It

Show: statusline cache counters across a few turns; then /model flip and watch creation spike.
They’ll trip on: casual mid-task model/effort switches — each one is a full re-read.

Learning path: ⬅ 53-devcontainers-sandbox-environments.md · Index · ➡ 55-troubleshooting.md

Written by Fenil Patel