Claude Code Learning Hub
中文 Mingyu's Library

Hub / Tips / D · Cost & context

Which actions invalidate the prompt cache?

Switched models, and the next reply is suddenly slow and expensive? You punched through the prompt cache — that turn is recomputing your entire conversation from scratch.

Claude Code resends the full conversation history to the API every turn; prompt caching is the only reason it isn't reprocessed each time. Know which actions break the cache and you can steer around the "suddenly slower and pricier" traps.

One-line answer

Bottom line The cache hits on an exact request-prefix match: any action that edits content at the start of the request (system prompt, tool definitions) or changes the cache key (model, effort, fast mode) forces a full recompute next turn. OfficialOfficial advice: settle on model and effort at the start of the session, save /compact for breaks between tasks — the fewer mid-session changes, the higher your hit rate.

Steps

  1. Understand how hits work first.OfficialModels keep no memory between requests; Claude Code resends the entire context every turn. The API matches the request "prefix" exactly against recently processed content: in a normal turn only the latest question and answer are new, and everything else is re-read at the cached rate (about 10% of the standard input price). Change anything in the prefix and everything after it is recomputed — there is no per-file or per-fragment partial caching. That's why Claude Code puts the least-changing content first:
    System prompt Core instructions · tool definitions Project context CLAUDE.md · memory · rules Conversation history New content appended each turn Almost never changes Loaded at session start Changes every turn (only this is recomputed) One change in an earlier layer (e.g. a model switch alters tool definitions) = everything after it recomputed Matching is exact: whichever layer you change is where the cache breaks
    The request is layered by how often each part changes; the cache breaks at the point of change, and everything after it is recomputed at the uncached rate.
  2. Memorize the 8 actions that invalidate it.OfficialThe complete list from the official docs:
    • /model switches: each model has its own cache — identical content is still fully recomputed; under the opusplan setting, every entry into and exit from plan mode counts as a model switch.
    • /effort changes: the cache key includes effort, so changing it mid-session pops a confirmation dialog first.
    • Turning on fast mode: the request header enters the cache key — a one-time cost; turning it off later, or rate-limit fallback, no longer invalidates.
    • MCP server connects/disconnects: only when tool definitions are loaded into the prefix (tool search disabled, alwaysLoad, and similar scenarios); the default deferred tools are unaffected. Details in Why too many MCP servers slow you down and cost more.
    • Enabling/disabling a plugin that ships an MCP server: same as above; plugins containing only skills/hooks/commands never break the cache.
    • Denying an entire built-in tool (e.g. a bare Bash): removes that tool from the system prompt; scoped rules like Bash(rm *) have no effect.
    • /compact: swaps the conversation layer for a summary, so it always invalidates; but done while the cache is still warm, the main cost is just generating the summary — a cold compact (after idling past the TTL) is the most expensive kind.
    • Upgrading Claude Code: new versions usually update the system prompt or tool definitions, so the first turn after restarting rebuilds the cache; --resume a long session right after an upgrade and that first turn may be the most expensive request you've ever sent.
  3. Know which actions do NOT invalidate — stop worrying about them.OfficialEditing repo files; editing CLAUDE.md mid-session (note: it doesn't take effect either — it only loads after /clear or a restart); changing output style (same caveat); switching permission modes; invoking skills and commands; /recap; /rewind; spawning subagents — these either only append to the end of the conversation or don't touch the request at all. Of these, /rewind returns to an already-cached prefix, which makes it cheaper than /compact when you want to abandon a dead-end path.
  4. Verify your own hit rate.OfficialEvery API response carries two fields: cache_read_input_tokens (hits, at roughly 10% of the price) and cache_creation_input_tokens (writes). Use a statusline script that reads current_usage to watch it live: high read with low creation is healthy; creation high every turn means the prefix keeps changing — work through the list above.
  5. Mind the TTL — don't mistake expiry for invalidation.OfficialIdle caches expire: subscriptions default to 1 hour, API keys and cloud providers default to 5 minutes (set ENABLE_PROMPT_CACHING_1H=1 to get 1 hour). After a long break, the first message always recomputes in full — that's not a mistake you made. For the mechanics, revisit D2 · Context window & prompt caching.

Copy-paste prompt

Check the prompt cache health of this session for me:
1. Set up a statusline script that shows cache_read_input_tokens and
   cache_creation_input_tokens from current_usage, and write it into my
   Claude Code statusline config (show me the script first for approval);
2. Explain how to read those two numbers: what a healthy hit rate looks
   like, and what indicates the prefix keeps getting broken;
3. Against the official list of cache-breaking actions (model switch,
   effort change, enabling fast mode, MCP server connect/disconnect,
   denying a whole built-in tool, /compact, resume after an upgrade),
   give me an "avoid doing these mid-session" cheat sheet.

Sources & last verified

  • Officialcode.claude.com/docs/en/prompt-caching.md (cache layering, invalidates/doesn't-invalidate lists, TTL, cache metrics), fetched 2026-08-05.
  • Our take"Use /rewind instead of /compact to abandon a wrong path — it's cheaper" is a paraphrase and arrangement of an official tip; the statusline troubleshooting steps are our own arrangement.
  • Last verified: 2026-08-05 · volatility:high (tied to current Claude Code behavior; official docs at v2.1.222, needs periodic re-checking).