How Claude Code Uses Prompt Caching

Prompt caching is the architectural foundation that makes Claude Code fast and economically viable. Without caching, the API would reprocess your entire conversation history on every single turn. With caching, it reuses what it already processed, billing re-reads at a 90% discount.

1. The Prefix-Matching Mechanism

Claude Code makes a fresh API request for every turn. The underlying model has no conversational memory between HTTP requests; Claude Code re-sends the complete prompt context: the system prompt, project context, previous messages, tool calls, and tool outputs.

The Claude API caches by matching the exact start of each request (the prefix) against content it recently processed. On a normal conversational turn, the prefix is the entire prior request, and only the latest user message and tool output are new.

The Prefix Rule: The match is strictly exact. A modification anywhere inside the prefix forces the model to recompute everything that comes after it. There is no per-file or per-segment caching.

2. The 3-Layer Request Hierarchy

To maximize cache hit rates, Claude Code structures every API payload in order of change frequency:

Because new conversational turns append to the end of Layer 3, Layers 1 and 2—and all earlier turns in Layer 3—remain completely cached.

3. Actions That Invalidate the Cache

When an action invalidates the cache, you will experience a one-time slower, more expensive turn while the prefix rebuilds:

• Switching Models (/model): Each model family (Opus, Sonnet, Haiku) maintains an isolated server-side cache. Switching models mid-session recomputes the entire conversation history from scratch.
• Changing Effort Levels (/effort): On most models, changing reasoning effort mid-session invalidates the cache. (Opus 5.5 and Sonnet 5.5 preserve cache across effort changes when using a Claude subscription).
• Connecting Upfront MCP Servers: When MCP tool search is disabled or unavailable, adding an MCP server introduces new tool definitions into Layer 1 (System Prompt), invalidating everything behind it.
• Compacting the Conversation (/compact): Compacting replaces the message history with a summary. By definition, the new summary does not match the old prefix, forcing Layer 3 to rebuild.
• Accumulating Excessive Images: When request image quotas are exceeded, Claude Code purges the oldest batch of screenshots, modifying historical messages and forcing re-caching from that turn onward.

4. Actions That Keep the Cache Intact

These actions are safe to perform mid-session without incurring uncached penalties:

• Editing repository files: File contents append to the conversation when read. Modifying a file adds a <system-reminder> without breaking prior history.
• Editing CLAUDE.md mid-session: CLAUDE.md is loaded once at startup. Mid-session edits do not invalidate the cache (and take effect only on the next /clear or restart).
• Toggling Permission Modes: Switching between Auto, Manual, and Accept Edits mode does not alter tool definitions or prompts.
• Rewinding turns (/rewind or Esc twice): Truncates history back to an exact earlier turn that is already warm in cache!
• Spawning Subagents: Subagents run in isolated conversations. Their execution appends as a single tool call in the parent session, leaving the parent prefix intact.

5. Cache Lifetime: 5-Minute vs 1-Hour TTL

Cached prefixes expire after a period of inactivity. Every request that hits the cache resets the timer. Anthropic provides two distinct Time-To-Live (TTL) tiers:

Unlocking the 1-Hour TTL on API Keys

If you connect via an Anthropic API key or cloud provider, configure the 1-hour cache in your global ~/.claude/settings.json:

{
  "promptCacheTtl": "1h"
}

Alternatively, set the shell environment variable:

export CLAUDE_CODE_PROMPT_CACHE_TTL="1h"

6. Monitoring Cache Hit Rates

Run /usage at any time during an active session to inspect real-time caching performance:

Prompt cache (main): 94% hit ratio (12 hits, 1 miss) • cache warm

If a miss occurs, Claude Code automatically reports the likely cause (e.g. likely cause: tool definitions changed). For automated monitoring, the OpenTelemetry exporter publishes cache_read_input_tokens and cache_creation_input_tokens.