Cache miss in Claude Code costs 12.5× more than a hit. Here are 5 things you do mid session that quietly trigger it

Two numbers from Anthropic's prompt caching docs that explain most of your token bill:

"5-minute cache write tokens are 1.25 times the base input tokens price." (source)

"Cache read tokens are 0.1 times the base input tokens price." (source)

That's the math: cache miss = 12.5× more expensive than cache hit for the same prefix. On a 50,000-token Claude Code session prefix (system + tools + CLAUDE.md + early turns), the difference per turn is real money — and most users bust their cache without noticing.

Anthropic publishes the exact invalidation table. Cache is built in this order: tools → system → messages. Changes at any level invalidate that level and everything after it. So not all cache busts are equal — some flush only the recent messages, others flush the entire prefix back to your tool definitions.

Here are the 5 actions in Claude Code that trigger this, ordered from "nukes everything" to "trims the tail":

1. Install or remove an MCP server mid-session — busts everything

Anthropic: "Modifying tool definitions (names, descriptions, parameters) invalidates the entire cache." MCP servers register tool definitions. Adding claude mcp add or running /mcp during an active session changes the tools block at the top of every cached request. Everything downstream — system, CLAUDE.md, full conversation — gets re-written at 1.25× cost.

Fix: install all your MCPs at session start. If you need a new one mid-task, finish the current task, /clear, then add.

2. Switch model with /model — cache namespace changes entirely

Caches are per-model. Switching from Sonnet to Opus mid-session doesn't migrate the cache; the prefix is processed fresh on the next turn. There's no warning in the UI.

Fix: pick the model at session start. Use Opus for planning, Sonnet for execution — but split them into separate sessions, not one session you keep flipping.

3. Edit CLAUDE.md while a session is open — busts system + messages

CLAUDE.md content is delivered as part of the system prompt area. Anthropic's invalidation rule: any system-level change invalidates the system cache and everything in the messages cache that built on it. Edit a single line in CLAUDE.md, save, send the next message → prefix below your CLAUDE.md gets re-written.

Fix: edit CLAUDE.md between sessions, not during one. If you must edit mid-session, /clear first so you don't pay to re-write a long conversation.

4. Toggle fast mode (Shift+Tab) — busts system + messages

Anthropic lists "speed setting" as a system-cache invalidator: "Switching between speed: 'fast' and standard speed invalidates system and message caches." Every Shift+Tab toggle re-writes the cached prefix.

Fix: pick one speed at session start and stay there. If you toggle 3 times across a session, you've paid the cache-write premium 3 times.

5. Paste an image mid-conversation — busts messages only

The lightest of the five. Per the invalidation table: "Adding/removing images anywhere in the prompt affects message blocks." Tools and system stay cached, but the entire messages prefix is processed fresh.

Fix: this one is often worth it (screenshots are high-signal). Just know that "let me drop a quick screenshot" isn't free — you're paying ~10% of your input bill to add it.

The general rule

Anthropic's exact phrasing: "Cache hits require 100% identical prompt segments, including all text and images up to and including the block marked with cache control."

100% identical. Not "mostly the same." One character changes in your CLAUDE.md, you pay 12.5× to process the next turn. This is why every Anthropic doc tells you to lock your configuration at session start.

Sources

• Prompt caching — Anthropic API docs (every quoted number is from this page)
• How Claude remembers your project — Anthropic Claude Code docs
• Best practices for Claude Code — Anthropic