Prompt Caching and Token Savings

Every time you send a message in Claude Code, it ships your entire conversation to the API. System prompt, CLAUDE.md files, tool definitions, full conversation history. Most of that content is identical between turns. You're paying full price for the same bytes over and over.

Prompt caching fixes that. And it's already on.

How It Works

It's basically a key-value store on Anthropic's servers. First time Claude Code sends a big block of content (system prompt, CLAUDE.md, tool definitions), the API stores a cached version of those processed tokens. Next request, if that same content appears in the same position, the API pulls from cache instead of reprocessing.

Cache reads cost roughly 90% less than uncached reads. Not a typo. 90%.

The catch: cache writes cost slightly more than a normal uncached read. So the first request where content gets cached is a bit more expensive. But every subsequent hit saves so much that the initial cost pays for itself almost immediately.

Caches have a TTL. Stop using Claude Code for a while, the cached content expires, and the next request triggers a fresh cache write. During active sessions though, you're hitting cache constantly.

The gotcha: content must be byte-identical for a cache hit. Change one character in your system prompt and the entire block gets re-cached. This is why stable content like CLAUDE.md and tool definitions cache so well.

What Gets Cached Automatically

You don't configure anything. Claude Code enables prompt caching by default and structures every request to maximize hits.

What's cached:

• System prompt — the internal instructions telling Claude Code how to behave. Same every turn, always cached after the first request.
• CLAUDE.md content — your project instructions, user instructions, nested CLAUDE.md files. Rarely change mid-session.
• Tool definitions — schemas for Read, Write, Edit, Bash, Grep, Glob, and everything else. Static. Cache perfectly.

Conversation history grows each turn, so only the prefix matching previous requests gets cached. New messages at the end are always uncached. But the big static blocks at the beginning? Cached every time.

Check your cache hit rate in the token usage display. High cache read percentages mean you're saving money.

Try it: Start a fresh session in a project with a CLAUDE.md file. Send two or three messages. Watch the token usage after each one. Cache read tokens climb while cache write tokens stay low after the first turn. That's caching doing its job.

Disabling Caching

Occasionally you'll want it off. Debugging token costs, testing performance without cache, running benchmarks with consistent pricing per request.

# Disable prompt caching globally for all models
DISABLE_PROMPT_CACHING=1 claude
 
# Disable caching only for specific models
DISABLE_PROMPT_CACHING_HAIKU=1 claude
DISABLE_PROMPT_CACHING_SONNET=1 claude
DISABLE_PROMPT_CACHING_OPUS=1 claude

How these interact:

• Global DISABLE_PROMPT_CACHING=1 overrides everything. Caching off for all models, period.
• Per-model flags only affect the named model. Disable for Haiku while keeping Sonnet and Opus cached.
• These are environment variables, not config file settings. Set them inline or export in your shell profile.

For day-to-day usage, leave caching on. It's free performance. The only legitimate reasons to touch these flags are debugging and specific testing scenarios.

# Debug a cost issue by running one session without cache
DISABLE_PROMPT_CACHING=1 claude "analyze this file" --print
 
# Disable caching only for Haiku requests
export DISABLE_PROMPT_CACHING_HAIKU=1
claude

Maximizing Cache Hits

Keep your CLAUDE.md stable during sessions. Every edit mid-session invalidates the cached version and triggers a fresh cache write. Edit between sessions, not during.

Don't restructure tool definitions. Claude Code handles this automatically, but if you're building custom MCP tool integrations, keep schemas consistent between requests.

Longer sessions beat many short ones. Each new session starts with a cache miss. Five messages in one session is cheaper than five separate one-message sessions. More turns, better cache hit ratio.

Watch your token stats. High cache write numbers and low cache read numbers across many turns means something is changing between requests that shouldn't be. Worth investigating.

The Gist

Cache reads cost about 90% less than uncached reads, and Claude Code enables this by default. System prompts, CLAUDE.md, and tool definitions are cached automatically. The main thing you can do to help: keep CLAUDE.md stable mid-session, since byte-identical content is required for hits. DISABLE_PROMPT_CACHING=1 is for debugging only. Longer sessions with more turns get better hit rates.