Claude code prompt cache metrics just landed in the /cost command — and honestly, this is the update cost-conscious builders have been waiting for. Wondering what hit ratio, misses, re-cached tokens and warm vs cold actually tell you? The quick version is just below, then we’ll go deep.
Short answer:
- v2.1.251 (28 August 2026, per the official Claude Code changelog) added per-session prompt-cache metrics to
/cost: "hit ratio, misses, tokens re-cached, warm/cold". - The same release enhanced session resumption with staleness and re-cache cost metrics — you can finally see what resuming an old session costs.
- v2.1.248 added an
experimental.cacheTtlagent frontmatter option for per-agent cache TTL. - Why care: caching is the single biggest lever on what a heavy Claude Code session costs you.
What Are Claude Code Prompt Cache Metrics?
Prompt caching is the quiet machinery that makes long Claude Code sessions affordable: instead of re-processing your entire conversation and context on every single turn, the model re-reads a cached copy of what it has already seen. When the cache works, turns are faster and dramatically cheaper. When it silently breaks, you pay full price for the same context over and over — and until this week, you mostly couldn’t see which one was happening.
That’s what changed. Per the official Claude Code changelog, v2.1.251 added per-session prompt-cache metrics to the /cost command — specifically “hit ratio, misses, tokens re-cached, warm/cold”. The same release also enhanced session resumption with staleness and re-cache cost metrics, so resuming yesterday’s session now shows you what that resume actually costs.
What /cost Now Shows You
Here’s how I read each metric, and what it’s telling you about your workflow:
| Metric | What it means | What to do with it |
|---|---|---|
| Hit ratio | How much of your context is being served from cache | High is good. If it drops, something in your workflow is invalidating cache — look at what changes at the start of each turn. |
| Misses | Requests that had to process context fresh | Occasional misses are normal (first turn, resumed sessions). Constant misses mean you’re paying full freight every turn. |
| Tokens re-cached | Context that had to be written back into cache | Big re-cache numbers after edits or resumes show you the true cost of breaking cache mid-session. |
| Warm/cold | Whether your session’s cache is live or expired | Cold sessions re-pay for context. If you’re constantly cold, your gaps between turns are longer than your cache lifetime. |
None of these numbers is new physics — the caching always worked this way. What’s new is that Claude Code finally shows you the dials instead of making you infer them from your bill.
🔥 Want this set up without the guesswork? If you want your Claude Code and agent costs audited and optimised — cache strategy, session design, model choice — this is bread-and-butter work in the community. Inside the AI Profit Boardroom you get four live calls a week, daily tutorials, done-for-you templates and a 30-day roadmap — alongside 3,700+ members building with the same tools.
Prefer to talk it through first? Book a free SEO strategy session and we’ll map out where AI agents fit in your business.
How to Use Claude Code Prompt Cache Metrics to Cut Spend
Here’s the playbook I’d run now that the numbers are visible:
- Baseline your heavy sessions. Run
/costat the end of a normal working session and note the hit ratio. You can’t improve what you haven’t measured. - Batch your interruptions. Long pauses can leave you cold. If the warm/cold flag keeps showing cold, group your work into focused blocks instead of drip-feeding prompts across the day.
- Watch resumption costs. The new staleness and re-cache metrics on session resumption tell you whether resuming that three-day-old session was cheaper than starting fresh. Sometimes it isn’t — now you’ll know.
- Tune per-agent TTL where it matters. v2.1.248’s
experimental.cacheTtlagent frontmatter (per the changelog) lets you configure prompt-cache TTL per agent — useful for long-running background agents with predictable rhythms. It’s experimental, so treat it accordingly. - Compare across your stack. Caching behaviour differs across providers and routers. I’ve written about the same idea elsewhere in the stack — see OpenRouter response caching and DeepSeek off-peak pricing — the theme is identical: the cheapest token is the one you don’t re-process.
My Workflow: Watching the Dials Weekly
I treat AI spend like ad spend: reviewed weekly, per workflow, with a number attached. The teams I work with that scale agents profitably all do a version of this — and the ones that get surprised by their bill never do. With these metrics in /cost, a five-minute Friday review now tells you which sessions are cache-efficient and which are burning money on re-processed context.
If you’re training up on Claude Code generally, my Claude Code training guide covers the fundamentals this builds on. And the broader lesson stands: late-August releases also shipped things like PreModelSwitch/PostModelSwitch hooks in the very same v2.1.251 — the platform is maturing into something you can genuinely run a business on, if you keep up.
The Bottom Line on Claude Code Prompt Cache Metrics
Claude code prompt cache metrics turn the biggest invisible cost lever in Claude Code into four numbers you can read in ten seconds: hit ratio, misses, tokens re-cached, warm/cold. Shipped in v2.1.251 on 28 August 2026 per the official changelog, alongside resumption staleness and re-cache cost metrics — and with per-agent TTL control available experimentally since v2.1.248.
Update, run /cost, and look at your hit ratio this week. If it’s ugly, that’s not bad news — that’s found money. And if you want a second pair of eyes on your whole AI cost structure, book a free SEO strategy session — or join us in the AI Profit Boardroom where we do this every week.
FAQ: claude code prompt cache metrics
What are Claude Code prompt cache metrics?
They’re per-session caching statistics added to Claude Code’s /cost command in v2.1.251 (28 August 2026, per the official changelog): hit ratio, misses, tokens re-cached, and warm versus cold status.
Which version added prompt cache metrics to /cost?
Version 2.1.251, per the official Claude Code changelog. The same release also enhanced session resumption with staleness and re-cache cost metrics.
Why does cache hit ratio matter?
Cached context is far cheaper to re-read than fresh input, so a high hit ratio means you’re re-paying for less of your context on every turn. A low ratio flags workflows that keep invalidating their own cache.
What does warm vs cold mean?
Warm means your session’s cached context is still live and reusable; cold means it has expired or been invalidated, so the next request re-processes context from scratch — slower and more expensive.
Can I control how long the cache lives?
v2.1.248 added an experimental.cacheTtl agent frontmatter option for per-agent prompt cache TTL configuration, per the changelog — so yes, at the agent level, if you opt into the experimental setting.
How do I see the metrics?
Update to v2.1.251 or later and run /cost inside a session — the per-session prompt-cache metrics appear there.
Related Reading
Where to go from here. If you want to turn your AI cost optimisation into actual revenue instead of another tab you never open, join the AI Profit Boardroom — 3,700+ members, four live calls per week, daily tutorials and a 30-day roadmap. Or book a free SEO strategy session and I’ll walk through your setup with you.
About the Author
Julian Goldie is an SEO agency owner with 10+ years in SEO, 394K+ subscribers on YouTube, a 100% job-success score on Upwork, 75K+ community members across his groups, and the author of a best-selling SEO book. He runs the AI Profit Boardroom community, and you can book a free SEO strategy session with his team any time — for agency work, book a call for a custom quote.
Last updated August 2026. This is the living guide to claude code prompt cache metrics — it gets updated as the tools change.
