| name | token-saver |
| description | Use when the user asks about token usage, context, or cost — "why is this so expensive", "am I burning tokens", "how do I save tokens", "what's eating my context", "should I clear or compact", "is my cache still good", or before/after actions that reset the prompt cache (switching model, changing effort, upgrading Claude Code). Also use when a session is long and the user is deciding whether to keep going, hand off, or start fresh. Advisory only — explains what is actually happening and recommends; never silently changes how thorough the work is. |
| audience | team |
Token Saver
Cost advisor for Claude Code sessions. Explain, recommend, let the user decide.
Never quietly become terse or skip work to save tokens — if a tradeoff exists, name it.
1. The mental model (lead with this)
Every follow-on message resends the whole conversation. The API is stateless. Caching
does not change that — it changes what those tokens cost.
Prices move; these multipliers have not. Teach the ratio, not the dollar figure.
| Token type | Cost vs. base input |
|---|
| Cache read | 0.1× |
| Base input (uncached) | 1× |
| Cache write, 5-minute | 1.25× |
| Cache write, 1-hour | 2× |
| Output | 5× — see caveat below |
The three cache figures are published multipliers. The output figure is not — it's an
observation that every model on today's price list happens to price output at 5× its base
input. Say it that way; don't call it a documented rule.
Break-even — Anthropic's own framing, better than any "N× cheaper" claim:
- 5-minute cache pays for itself after 1 read
- 1-hour cache pays for itself after 2 reads
Two things people get wrong:
- Cached tokens still occupy the context window. Caching is a discount, not a diet.
- Total input =
input_tokens + cache_read_input_tokens + cache_creation_input_tokens.
Reading input_tokens alone undercounts badly — it only covers tokens after the last
cache breakpoint.
2. How long the cache lives
There is no single answer. Do not state "1 hour" as a universal fact.
| Where | Default TTL |
|---|
| Claude API / Bedrock / Vertex / Foundry | 5 minutes |
| Claude Code on a Claude subscription | 1 hour (requested automatically) |
| Claude Code running on usage credits (past plan limit) | drops to 5 minutes |
| Subagents | 5 minutes, even on a subscription |
- Refreshing is free — each cache hit resets the timer at no cost.
- The clock starts when the request begins, not when the response ends. A long streamed
reply eats into the window.
- Scope is one machine + one directory. The system prompt embeds the working directory,
so two sessions in different folders never share a cache — including worktrees of the
same repo.
3. What actually breaks the cache
The prefix match is exact: a change anywhere invalidates everything after it. Layers, in
order — system prompt → project context (CLAUDE.md, memory) → conversation.
Two cache-key inputs aren't in the prompt text at all: the model and the effort level.
Reliably invalidates
| Action | Note |
|---|
Switch model (/model) | The only truly unconditional one. Each model has its own cache; plan-mode toggles count. |
Change effort (/effort) | Except a no-op change to the level already in effect. |
| Upgrade Claude Code | Docs hedge — it typically changes the system prompt or tool definitions. Applies at next launch. |
Sometimes — the nuance most advice gets wrong
| Action | Actually |
|---|
| Fast mode | First enable only. Turning it off, rate-limit fallback, and re-enabling all keep the cache. |
| MCP connect/disconnect | Cache survives when tools are deferred (the default). Only bites when tool definitions sit in the prefix. |
| Plugin on/off | Only plugins that ship MCP servers. Skills, commands, agents, hooks: no effect. |
| Denying a tool | Only a whole-tool deny rule (Bash, WebFetch). Denying one call at a prompt does nothing. Scoped rules like Bash(rm *) are fine. |
/compact | Invalidates the conversation layer. Project context re-hits only if CLAUDE.md and memory are unchanged since session start. The expensive part is the compaction itself, not the turn after it. |
Does NOT break the cache — reassure people about these
Editing repo files · editing CLAUDE.md mid-session · changing output style · changing
permission mode · running skills and commands · /recap · /rewind · spawning a subagent.
/clear is different — be precise about it. It costs nothing to run, which is why
it's usually the right call. But it does not preserve your cache either: it starts a fresh
conversation with empty context, so the conversation layer is rebuilt from there. Cheap and
correct — just don't tell people it "keeps the cache."
Frame the cost honestly: a broken cache is one slower, pricier turn — then the new
prefix is cached. Not a permanent penalty.
4. Inspecting reality
| Command | Shows |
|---|
/usage (/cost is an alias) | Session totals incl. cache read and cache write tokens |
/context | Grid of what's filling the context window + optimization hints. Not a cache tool. |
/doctor | Finds unused skills, MCP servers and plugins vs. their context cost. Reports first, asks before changing anything. |
5. Long session — clear, compact, or hand off?
Ask what needs to survive, then recommend:
| Situation | Recommend | Why |
|---|
| Work is visible in the files/repo | /clear | Free. Claude re-reads the code and picks it up. Most common right answer. |
| Reasoning matters but isn't written down | /compact | Keeps a summary in the conversation. |
| You want a durable record across sessions | Write a handoff file | A markdown file on disk beats a summary that lives only in one chat. |
| Session is huge (500k+) | Any of the above | Past a point, quality degrades from context rot regardless of cost. |
Say this out loud when it applies: long sessions aren't just expensive, they get worse.
Cost is often the smaller problem.
6. Reducing spend, in order of impact
- Don't fragment the cache. Batch model/effort changes; don't flip settings mid-flow.
- Trim what loads every session.
/context then /doctor. Every skill's name and
description sits in context permanently — a large skill library is a standing tax.
- Keep CLAUDE.md short. Long ones don't just cost context — Anthropic notes they
reduce how well instructions are followed. Bloat makes Claude worse, not just pricier.
- Watch output. Output is 5× input. Asking for a whole file back when a diff would
do is the most common avoidable spend.
- Right-size the model for mechanical work.
7. Never say these
- ❌ "The cache lasts an hour" — depends on surface; 5 minutes is the API default
- ❌ "Cache reads are 20× cheaper" — Anthropic never publishes that; use break-even
- ❌ "Caching means the conversation isn't resent" — it is, every turn
- ❌ "Cached tokens don't count toward context" — they do
- ❌ "The minimum cacheable prompt is 1,024 tokens" — it's per model (512 / 1,024 / 2,048 / 4,096)
- ❌ "MCP / plugins / denying a tool always break the cache" — all three are conditional
- ❌ "Subagents give you a per-token discount" — there is no rebate. The saving is real but
indirect: work happens in a separate context so your main conversation doesn't carry it
forward, and you can route the sub-task to a cheaper model. Anthropic files this under
reducing token usage — so don't over-correct and claim it saves nothing.
- ❌ Quoting per-million dollar figures as the teaching unit
8. When exact numbers are needed
Send the user to the live source rather than quoting figures that will age:
https://platform.claude.com/docs/en/about-claude/pricing
