Prompt caching in Claude Code: what breaks the cache and what's safe

Everything is running smoothly, then you switch /model to Opus and the next turn is suddenly slow and usage jumps. Or you edit CLAUDE.md mid-session and Claude keeps following the old version. Both come down to prompt caching: Claude Code automatically caches the start of each request, and some actions "break" the cache. The new Claude Code docs list exactly which actions break it, which are safe, and how to measure your cache hit rate. Knowing this is the cheapest way to save tokens.

How the cache is organised

Each turn, Claude Code re-sends the full context. The API matches the start (prefix) against what it just processed; an exact match is read from cache at a low rate, and anything that differs is recomputed from that point on.

Actions that break the cache

• Switching models: each model has its own cache, so the next turn rereads the whole conversation uncached. opusplan switches models on every plan-mode toggle; a skill with a different model field also counts as a switch.
• Changing effort: breaks the cache on most models. Opus 5.5, Sonnet 5.5, Haiku 5.5 and Fable 5.1 (with an API key or Claude subscription) keep it.
• Toggling fast mode: the two speeds keep separate caches; turn it on at the start of a session.
• Adding/removing MCP servers, denying a whole tool: breaks the cache when tools are loaded upfront; with tool search active (the default on supported models), the cache survives.
• /compact: replaces history with a summary, so the conversation layer is rebuilt. Compacting while the cache is warm is cheap; compacting an old, cold session costs the most.
• Many images: past the limit, Claude Code drops a batch of old images and recomputes from there.
• Upgrading Claude Code: the first session after an upgrade builds its cache from scratch.

Safe actions

• Editing files in the repo (Claude is told the file changed and rereads it if needed).
• Editing CLAUDE.md mid-session: the cache stays intact, but the edit doesn't apply until /clear, /compact or a restart.
• Changing permission mode, changing output style, invoking skills/commands, /recap.
• /rewind: truncates back to an already-cached prefix, cheaper than compacting when you want to abandon a direction entirely.
• Spawning a subagent: the main session's cache is unaffected.

Cache lifetime

The API offers two TTLs: 5 minutes and 1 hour (with pricier cache writes). By default, Claude subscriptions (within plan usage) get 1 hour for the main conversation; API keys and cloud providers get 5 minutes. Choose your own with promptCacheTtl (main conversation) and subagentPromptCacheTtl, set to 5m or 1h.

// ~/.claude/settings.json: API key user who often steps away
{ "promptCacheTtl": "1h" }

Measuring your hit rate

• /usage shows a Prompt cache (main) line: hit ratio, miss count, whether the cache is warm, and the likely cause of the last miss.
• A statusline can read cache_read_input_tokens and cache_creation_input_tokens: lots of reads and few writes is good; consistently high writes mean your prefix keeps changing.

Risks and caveats

• Gateways that strip cache markers: if a gateway removes cache_control, the whole conversation bills as uncached on every turn.
• A 1-hour TTL isn't always cheaper: if you work continuously without 5-minute gaps, the higher write rate is wasted.
• The cache is tied to machine and directory: sessions in another directory don't share it.

How to apply it

• Dev: Choose model, effort and fast mode at the start of a session; compact at natural breaks between tasks; to abandon a wrong direction, /rewind instead of compacting.
• Tech Lead: Check that your internal gateway forwards cache_control and beta headers unchanged.
• PM: When usage looks unusual, check the Prompt cache (main) line in /usage before concluding you need a bigger plan.