Prompt Caching: Your Biggest Hidden Cost Lever
- Explain how prompt caching reduces per-turn cost by serving repeated content at the cached token rate
- Identify the four actions that invalidate the cache and force a full re-read of the context window
- Describe the difference in cache lifetime between subscription plans, usage credits, and API keys — and how to choose the TTL yourself
Why Most Turns Are Much Cheaper Than They Look
Claude Code sends your full conversation history with every request. In a session that has been open for an hour with many file reads and tool results, that could be 100,000+ tokens on every turn. Without caching, every question would cost a full re-read of everything. Prompt caching means that after the first request, Claude Code serves that repeated content from cache at a fraction of the normal input token rate — typically around 10% of the standard input price.
This is the single largest cost-reduction mechanism in Claude Code. A session with a 91% cache hit rate is paying roughly 10x less per turn than the same session without caching. The /usage prompt cache stats line shows you exactly how much you are benefiting.
How the Cache Works
After your first API request in a session, Claude Code stores the conversation prefix in a cache. Subsequent requests check whether the beginning of the new request matches the cached prefix. If it does, that portion is served from cache at the reduced rate. Only the new content — your latest message and any new tool results — is processed at full input price.
The cache is keyed to the exact content of the conversation prefix. Any change to that content, even a small one, requires re-processing and re-caching.
The Four Cache Killers
These actions invalidate the cache and force a full re-read of your context on the next turn:
Starts a new session with empty context. The cache resets with the conversation. This is expected behavior — a fresh start means fresh caching. The next first request re-caches everything.
Running /compact or triggering auto-compaction rewrites the conversation history, which invalidates the cached prefix. Claude Code counts this as an expected rebuild in the cache stats.
When context fills, Claude Code clears old tool results to make room. This also invalidates the cache prefix — another expected rebuild.
The cache has a lifetime. After the session has been idle longer than the TTL, the cache expires. The next request reprocesses and re-caches the full history at full input price.
Cache Lifetime and Why It Matters
Cache lifetime varies by how you authenticate and what you are spending:
- Subscription plan (Pro, Max, Team, Enterprise) within seat allowance: 1-hour TTL. A one-hour break between turns is fine; longer breaks mean a cold cache on the next request.
- Usage credits (subscription plan drawing past the seat allowance): drops to 5-minute TTL. This is the painful one — a brief break in a large session can trigger a full re-read that consumes a significant amount of your credit.
- API key or cloud provider: 5-minute TTL by default.
On a Pro or Max plan, you can choose the TTL yourself to keep the 1-hour lifetime even when drawing on usage credits. The setting is available through the API; check the prompt caching docs for the exact parameter.
Keeping the Cache Warm
The practical rule: stay active within the cache lifetime. A session that receives a turn at least every 55 minutes (on the 1-hour TTL) keeps the cache warm continuously. When you need to step away, check your cache state in /usage before the first long break — if the session is large and the cache will expire, either compact first or be prepared for a more expensive re-cache turn when you return.
On Pro or Max plans, when you resume a session that has been inactive more than an hour and is over 100,000 tokens, Claude Code offers a dialog: resume from summary (compacts first, cheaper subsequent turns), or resume full session (re-caches full history, more expensive next turn, but preserves all context). That choice is covered in depth in lesson 6.
- Prompt caching serves repeated content at ~10% of the standard input rate — a session with 91% cache hit rate is paying roughly 10x less per turn than uncached; this is the single largest cost lever in Claude Code.
- Four actions invalidate the cache: /clear, compaction (/compact or auto-compact), tool result clearing when context fills, and idle timeout — after any of these, the next request re-processes the full context at full price.
- Cache lifetime is 1 hour on subscription plans within the seat allowance but drops to 5 minutes when drawing on usage credits or using an API key — be aware of this boundary when you expect heavy usage.
- The /usage prompt cache stats line shows your hit rate, miss count, and warm/cold state — check it when a session feels more expensive than expected.
- On Pro/Max plans, choose your cache TTL explicitly to keep the 1-hour lifetime even when drawing on usage credits; this matters most for large, long-running sessions.