Your editor cost the same whether you fixed one failing test or fifty. Agentic coding tools break that assumption. The same one-line fix can cost two, five, or ten times as much depending on how the session that produced it was run — and most of that difference has nothing to do with the fix itself.
Consider two sessions that both fix the same test. In the first, you name the file. Claude reads it, reads the module it imports, makes a one-line edit, runs the test, and reports back. Five requests, two files. In the second, you say "the tests are failing." Claude greps the repo, reads a dozen candidate files, finds the culprit, and makes the same one-line edit. It arrives at the identical diff — but every one of those dozen files rides along in every subsequent request, and the model spends every remaining turn reasoning around ten files that never mattered.
The lesson is not "use fewer tokens." Token efficiency, properly understood, means that every token you pay for is spent on the thing you actually asked for. This guide gives you the cost model needed to see where that isn't happening, with real prices and worked arithmetic, and then a workflow built on it.
A note on numbers. Prices and multipliers below come from Anthropic's published pricing and documentation. The token counts in the worked examples are assumptions chosen to be realistic; they are marked [illustrative] wherever they appear. The ratios are what matter, and the ratios hold.
Contents
- 1. What a Token Costs
- 2. Anatomy of a Session
- 3. What Breaks the Cache
- 4. What Fills the Context
- 5. Session Length and the Turn Loop
- 6. Is Mid-Task Compaction Dangerous?
- 7. Subagents: A Different Context
- 8. Choosing Model and Effort
- 9. The Workflow: Plan Big, Execute Small, Never Switch Mid-Session
- 10. Measuring It
- 11. Checklist
- 12. Tools That Claim to Save Tokens
- References
Quick lookup
| I want to… | Go to |
|---|---|
| See current prices and cache multipliers | 1.3 Prompt caching — full price card |
| Understand what one turn costs | 2.3 The per-turn bill as a formula |
| Know if my sessions are healthy | 2.4 What a healthy session looks like — the 84% benchmark |
| Know what breaks the cache | 3. What Breaks the Cache |
| Decide whether to switch model or effort mid-task | 3.2 and 3.3 |
| Write better prompts for cost | 4.2 The three-prompt experiment |
| Stop test output polluting context | 4.3 Command output |
| Decide: continue / rewind / clear / compact / subagent | 5.2 The turn-end decision |
| Compact safely mid-task | 6. Is Mid-Task Compaction Dangerous? |
| Set up a subagent with its own model | 7.3 Defining subagents — frontmatter example |
| Pick a model and effort for a task | 8.3 A starting table |
| Plan on one model and execute on another | 9.2 Case: plan on Fable, execute on Sonnet |
| Measure what I'm spending | 10. Measuring It |
| Just give me the habits | 11. Checklist |
| Decide whether rtk / caveman / a router is worth installing | 12.7 Summary table |
1. What a Token Costs
You are billed per token, but what you are buying is inference time — GPU-seconds, more or less. Three things determine how much time a given token costs: which model processes it, whether it is input or output, and whether the server had already seen it.
1.1 Model is a multiplier on everything else
Current list prices, US dollars per million tokens:
| Model | Input | Output |
|---|---|---|
| Haiku 4.5 | $1 | $5 |
| Sonnet 5 | $2 | $10 |
| Opus 5 | $5 | $25 |
| Fable 5.1 | $10 | $50 |
Haiku to Fable is a 10x spread on input. Every other lever in this article — caching, context size, session length — gets multiplied by this number, which is why model choice is the first decision, not the last.
1.2 Output costs about five times input
A request has two phases. Prefill reads the entire prompt — system prompt, CLAUDE.md, your messages, every file and command output already in the conversation — in a single forward pass. Decode then generates the response one token at a time, and every token requires the model to run again. A 200-token reply is 200 sequential runs. That is why output is priced at roughly five times input across the lineup.
Two consequences follow. First, thinking tokens are output tokens, billed at output price; a turn that thinks for 5,000 tokens and replies in 500 is a 5,500-token output bill. Second, the /effort setting — which controls how much work Claude does per turn, including how many files it reads, how many tools it calls, and how long it thinks before checking back in — is a direct lever on your most expensive token class. Effort persists across sessions, so a new session inherits whatever you set last time. Check it deliberately.
1.3 Prompt caching: the 10x that runs every turn
If the beginning of a request is byte-identical to a request the server has recently processed, the server reuses its internal state for that prefix and only prefills the new tail. This is prompt caching, and it is the single largest factor in what a Claude Code session costs.
| Operation | Price relative to input |
|---|---|
| Cache read | 0.1x (Fable 5.1: 0.025x) |
| Cache write, 5-minute TTL | 1.25x |
| Cache write, 1-hour TTL | 2x |
Writing to the cache costs more than a plain read of the same tokens, so a prefix that is only ever read once is a net loss. But a Claude Code conversation is read on every single turn, and the write pays for itself after one read (5-minute TTL) or two (1-hour). Claude Code on a subscription requests the 1-hour TTL automatically; on an API key you get 5 minutes unless you set ENABLE_PROMPT_CACHING_1H=1.
Fable 5.1's cache reads are priced at $0.25 per million — cheaper than Opus 5's $0.50, and a quarter of its own already-low ratio. That is a deliberate signal about how Anthropic expects Fable to be used: in long sessions where the same large context is read again and again.
The full price card:
| Model | Input | Output | Cache write (1h) | Cache read |
|---|---|---|---|---|
| Haiku 4.5 | $1 | $5 | $2 | $0.10 |
| Sonnet 5 | $2 | $10 | $4 | $0.20 |
| Opus 5 | $5 | $25 | $10 | $0.50 |
| Fable 5.1 | $10 | $50 | $20 | $0.25 |
Claude Code manages caching for you. You cannot turn it on or off. What you can do — and, as Section 3 shows, what you may be doing without realising — is break it.
2. Anatomy of a Session
2.1 The five-request fix
Take the good session from the introduction: "fix the failing test in utils.test.ts." Here is what actually goes over the wire.
Request 1. Tool definitions, system prompt, CLAUDE.md, your message. Nothing is cached yet; everything is prefilled at full price and written to the cache. Claude decides to read the test file.
Request 2. Everything from request 1 — now a cache hit — plus the Read call and the file's contents, prefilled fresh. Claude reads the source file.
Request 3. Requests 1 and 2 cached, plus the second file. Claude makes an Edit.
Request 4. Everything so far cached, plus the edit and its confirmation. Claude runs the tests.
Request 5. Everything cached, plus the test output. Claude writes its summary. No sixth request, because the summary is the end of the turn.
Every request resends the entire conversation, and the cache is matched from the front. The order is fixed — tool definitions, then system prompt, then the conversation with CLAUDE.md at its head — so the stable, expensive material is always in the cacheable position and only the newest tail is paid for at full price.
2.2 Worked numbers [illustrative]
Assume a system prompt and tool definitions of about 20,000 tokens, a 1,500-token CLAUDE.md, a 500-token message, files of 2,000 and 1,500 tokens, 1,000 tokens of test output (quiet reporter), and roughly 350 output tokens per turn for thinking and tool calls.
| Request | Cache read (0.1x) | New / written (2x) | Output |
|---|---|---|---|
| 1 | 0 | 22,000 | 400 |
| 2 | 22,000 | 2,200 | 400 |
| 3 | 24,200 | 1,700 | 400 |
| 4 | 25,900 | 500 | 300 |
| 5 | 26,400 | 1,000 | 300 |
| Total | 98,500 | 27,400 | 1,800 |
Of the roughly 126,000 tokens sent, 78% are cache reads. Now the cost, per model:
| Model | Writes | Cache reads | Output | Total | Without caching |
|---|---|---|---|---|---|
| Haiku 4.5 | $0.055 | $0.010 | $0.009 | $0.07 | $0.13 |
| Sonnet 5 | $0.110 | $0.020 | $0.018 | $0.15 | $0.27 |
| Opus 5 | $0.274 | $0.049 | $0.045 | $0.37 | $0.67 |
| Fable 5.1 | $0.548 | $0.025 | $0.090 | $0.66 | $1.35 |
Three things to notice. The model spread is 9x for identical work. In a session this short, the first-turn write dominates — three quarters of the Sonnet bill is the one-time cost of putting 22,000 tokens of system prompt into the cache. And Fable's cache reads cost less in absolute terms than Opus's, which means the gap between them narrows as sessions get longer.
2.3 The per-turn bill as a formula
Each turn costs, approximately:
history × 0.1 × input_price + new_tokens × 2 × input_price + output × output_price
Which term dominates depends on where you are. Early in a session, the write term does, because the system prompt is being cached for the first time. In the middle, history reads and thinking output take over. And on any turn where the cache breaks, the history term stops being multiplied by 0.1 and starts being multiplied by 2 — a 20x jump on a single line item.
2.4 What a healthy session looks like
Anthropic publishes benchmarks for this. Across real agent traffic, the median agent loop reads 84% of its input from cache; the best 10% of harnesses exceed 94%. Deep in a task, a well-behaved loop pays full price on less than 1% of its input. If your sessions look meaningfully worse than that, something in Section 3 or 4 is going wrong.
The same documentation makes a point that reshapes how you should think about session length: a 40-turn task sends its first turn 40 times. Total cost grows roughly with the square of the number of turns.
3. What Breaks the Cache
The cache is matched from the first byte. Change anything near the front and everything after it is re-prefilled at full price. In Claude Code, these are the operations that do it.
/model. Each model has its own cache. Switching mid-conversation means the new model has never seen any of it; the entire conversation is prefilled and written from scratch. This includes opusplan, which switches models on every entry to and exit from plan mode.
/effort. Effort level is part of the cache key. Changing it has the same effect as changing model. This is why both commands ask you to confirm when invoked mid-conversation.
Fast mode. Also part of the key. Enabling it re-prefills at fast-mode prices. If you want it, turn it on at the start; turning it off is free, because the cache for the normal-speed path is still there.
/compact. Compaction replaces the conversation with a summary. The system prompt in front survives; everything after it is new. Compacting is cheap while the old conversation is still cached (reading it is 0.1x) and expensive after the cache has expired (reading it is full price, before you even get to writing the summary).
Time. One hour on a subscription, five minutes on an API key. Come back from lunch and the first turn re-prefills everything. Resume yesterday's session and it certainly does.
3.1 What one cache break costs [illustrative]
Take a 100,000-token conversation — a medium-length Claude Code session — and compare a normal turn with the turn immediately after a break:
| Model | Normal turn (100k × 0.1) | After break (100k × 2) | Penalty |
|---|---|---|---|
| Haiku 4.5 | $0.01 | $0.20 | 20x |
| Sonnet 5 | $0.02 | $0.40 | 20x |
| Opus 5 | $0.05 | $1.00 | 20x |
| Fable 5.1 | $0.025 | $2.00 | 80x |
Fable's cheap reads make its cache breaks proportionally the most expensive in the lineup. On a subscription you will not see dollars, but the same request draws down your usage allowance by the same proportion.
3.2 Cheap moments and expensive moments
None of this means you should never switch. It means switching has a time. At the start of a session, or immediately after /clear, there is nothing to re-prefill and a model or effort change is free. In the middle of a long conversation it is the most expensive thing you can do short of starting over.
/rewind deserves special mention because it is the one context operation that is genuinely free. It removes turns from the end of the conversation; everything before the rewind point is still an exact cache match. If Claude went down a wrong path, rewinding to before the mistake and re-prompting with what you learned costs nothing and leaves your context cleaner than a correction would. Compaction, by contrast, always rewrites.
3.3 Case: dropping effort when the budget is almost gone [illustrative]
A common instinct: you are mid-task on Opus at high effort, you notice your five-hour allowance is nearly spent, and you drop to low effort to stretch what is left. Does it help?
The switch itself costs a full re-prefill. On a 100,000-token conversation that is the equivalent of about 200,000 full-price input tokens in one turn. What it saves is thinking output — perhaps 2,700 tokens a turn if high effort was thinking around 3,000 and low thinks around 300, or roughly $0.07 a turn on Opus. Break-even is around fifteen turns. If you have fewer than fifteen turns of work left, the switch is a net loss, and the 200,000-token spike may itself push you over the limit you were trying to protect.
The right sequence, if you must switch: /compact first, while the cache is still warm, so that the conversation shrinks to 10–15,000 tokens. Then /effort low. The re-prefill is now a seventh the size, and every remaining turn reads a small history and thinks less. Never do it in the other order — that pays for a full-size rewrite, then a second one.
Often the better answer is not to switch at all: push to the nearest green checkpoint, commit, write a progress note to a file, and stop until the window resets. Section 6 explains why that is safe.
4. What Fills the Context
Everything that enters the conversation stays there until the session ends, and it is re-sent — and re-read by the model — on every turn. Cached, so it is cheap; but not free, and not weightless. The model has to attend past it every time.
4.1 The baseline you carry before you type
A fresh session already contains tool definitions, the system prompt, CLAUDE.md, and the definitions for every MCP server you have connected. Run /context in a new session to see the total. Two adjustments pay off immediately: keep CLAUDE.md to instructions that apply to every session and move workflow-specific guidance into skills, which load only when used; and use /mcp to disable servers you are not using today. Their tool definitions are otherwise in every request you send.
4.2 Tool results, and the three-prompt experiment
Most of what accumulates during a session is tool output — files Claude read and commands it ran. How much accumulates is largely a function of how precisely you asked.
| Prompt | What Claude does | Cost shape |
|---|---|---|
| "the tests are failing" | greps, reads several candidates | grep output and irrelevant files persist for the whole session |
"fix the failing test in utils.test.ts" |
one Read | one file in context |
"fix the failing test in @utils.test.ts" |
zero Reads | file attached before the first request |
The @ form is the interesting one. The file is included in your first message, so Claude never spends a turn deciding to read it — no tool call, no output tokens, one fewer request. Mention a file once per conversation; a second @ attaches a second copy.
Worked numbers [illustrative]. If the vague prompt triggers two greps of about 3,000 tokens each and three unnecessary file reads of about 2,000, and takes ten turns instead of five, the extra 12,000 tokens enter early and are re-read on every subsequent turn. Total cache reads rise from 98,500 to roughly 315,000. On Sonnet the fix costs about $0.27 instead of $0.15; on Opus, $0.67 instead of $0.37. The precise prompt is 1.8x cheaper and the model spent the whole session looking at the right two files.
4.3 Command output: the under-30,000-character problem
Claude Code protects you from the worst case. Command output over 30,000 characters is written to a file and only a preview enters the conversation (the threshold is BASH_MAX_OUTPUT_LENGTH). The problem is everything under that line. Four hundred lines of passing-test output is about 5,000 tokens — comfortably under the threshold, and it stays in context for every remaining turn even though nothing in it was useful.
The fix is to tell Claude how you would run the command yourself. Put the quiet form in CLAUDE.md — npx vitest run <file> --reporter=dot, cargo test -q, ./gradlew test --console=plain — and Claude will use it. If you want it enforced rather than suggested, a pre-tool hook can rewrite the command.
Worked numbers [illustrative]. Dot reporter output is about 100 tokens. The difference of 4,900 tokens, re-read over thirty remaining turns, is 147,000 extra cache-read tokens — $0.03 on Sonnet, $0.07 on Opus. Small. But that is one test run. Ten test runs in a session is 50,000 tokens of permanent noise, and the noise is the real cost.
4.4 The cost that isn't on the bill
Anthropic's own best-practices guidance is blunt about this: the context window is the most important resource to manage, because performance degrades as it fills. A model with 150,000 tokens of accumulated tool output in front of it forgets earlier instructions and makes more mistakes than the same model at 30,000. The community term is context rot, and it is why the guidance treats context as active working memory rather than an archive.
Compaction exists to fight this. When Claude Code compacts, it passes the history to the model and asks for a summary that preserves architectural decisions, unresolved bugs, and implementation details while discarding redundant tool output. It works well. It is also lossy by design, and Section 6 is about managing that.
5. Session Length and the Turn Loop
5.1 Quadratic growth, and what to do about it
Because every turn re-sends every previous turn, a 40-turn session costs substantially more than two 20-turn sessions doing the same work — even after paying twice for the system prompt. At forty turns the difference is around 15% [illustrative]; it widens quickly past that.
Two habits follow. When the task changes, /clear. When the same task has a natural midpoint — the investigation is done and the implementation is starting — /compact with an instruction about what to keep. If you will want the old session back, /rename it before clearing.
5.2 The turn-end decision
The end of every turn is a branching point with five options: continue, /rewind, /clear, /compact, or hand the next step to a subagent. The choice depends on one question — how much of the existing context is load-bearing for what comes next? If all of it, continue. If a recent detour poisoned it, rewind. If none of it, clear. If the conclusions matter but the evidence doesn't, compact. If the next step will generate a lot of evidence you won't need afterwards, subagent.
A new task gets a new session. Closely related follow-on work — writing documentation for what you just built — can legitimately reuse the context.
5.3 Compacting well
Manual /compact with a hint — "focus on the auth refactor, drop the test debugging" — is better than waiting for autocompact, for a reason that is easy to miss: autocompact fires when the context is fullest, which is exactly when the model is least able to write a good summary. If your compaction instructions are always the same, put them in a "Compact instructions" section of CLAUDE.md. On 1M-context models, /autocompact 200k re-enables automatic compaction at a sane threshold.
5.4 Turns that happen while you're away
/loop runs a prompt on a schedule. Each run is a full turn with the full conversation attached, and if the interval exceeds the cache TTL, each run is a cache miss too. Run loops from a fresh session in another terminal, not from the session you are working in.
6. Is Mid-Task Compaction Dangerous?
Yes, and it is worth being precise about how.
What a compaction summary loses is in-flight state: which three of five files are already changed, which tests were passing before the current edit, a design decision that was made in conversation but never written down, an approach you rejected out loud. When the summary drops one of these, the model may redo finished work, undo a deliberate choice, or resurrect a rejected option. It will do so confidently, because from its perspective the summary is the whole history.
But compaction is not optional. If you never compact manually, autocompact will do it for you when the window fills — at the worst possible moment, with no instructions from you. The choice is not whether to compact. It is whether you control the timing and the content.
Five practices make it safe.
Compact at green points, never mid-edit. After tests pass, after a subtask closes, after a commit. In-flight state is smallest there, so there is least to lose.
Keep state on disk, not in the conversation. Commit before compacting — a WIP commit is fine. File state now lives in git, not in the summary. The summary only has to preserve the why; the model can git diff for the what.
Dump progress to a file first. "Write current progress, remaining steps, and decisions made with their reasons to PROGRESS.md." A few hundred output tokens. Then tell the compaction to keep the path. If the summary loses something, @PROGRESS.md restores it next turn.
Give explicit keep-instructions. Objective, done/not-done list, files involved, rejected approaches and why, the test command.
Verify after. One turn: "summarise the current state and next step." Compare against PROGRESS.md. Catching drift now costs one turn; catching it ten turns later costs ten.
The pattern behind all five has a name in the community: document and clear. Never let a long session be the only record of what you decided. Commit often, write progress to files, and treat every session as disposable.
7. Subagents: A Different Context
7.1 Mechanics
A subagent runs in its own context window with its own system prompt, tools, and CLAUDE.md. It does not have your conversation. It does its work, returns an answer to the main session, and everything else it read or ran is discarded.
The trade-off is exact. The subagent may re-read files the main session already had, and it pays for its own turns; for a small job that is pure overhead. But for a job that generates a lot of output you only need the conclusion of — reading a log, running a test suite, grepping a large codebase — it keeps all of that out of the context you are actually working in. The test is one question: will I need this tool output again, or just the conclusion? Twenty file reads, twelve greps, and three dead ends stay in the child; only the report comes back.
You can invoke one inline — "go through this log in a subagent" — and Claude Code will do it.
7.2 Worked numbers [illustrative]
A 20,000-token log, main session on Opus with thirty turns still to go.
Read it in the main session: 20,000 tokens written at 2x Opus input ($0.20), then re-read thirty times at 0.1x ($0.30). About $0.50, plus 20,000 tokens of noise in every remaining turn.
Send it to a Haiku subagent: 20,000 written at 2x Haiku input ($0.04), plus a few turns of its own ($0.02). About $0.06, and the main session receives a few hundred tokens of findings.
The counter-case is just as real. A task that needs one 2,000-token file, sent to a subagent, rebuilds a 22,000-token system prompt in a fresh context — $0.22 on Opus — to save the main session $0.02. Small jobs stay in main.
7.3 Defining subagents
For a job you delegate repeatedly, define it once. Subagents are Markdown files in .claude/agents/ (project) or ~/.claude/agents/ (personal) with YAML frontmatter. The fields include description, tools, model, effort, maxTurns, skills, and memory. model accepts an alias (haiku, sonnet, opus), a full model ID, or inherit, which is the default — and the default is the trap, because it means your log-reading subagent runs on whatever your main session is running on.
[↑ Contents](#contents)
---
name: log-digger
description: Analyse test output or logs. Return only failures, stack traces, and likely root causes.
tools: Read, Bash, Grep
model: haiku
effort: low
[↑ Contents](#contents)
---
Report failing tests, error stacks, and your best assessment of the root cause.
Do not restate passing cases. Keep the report under 300 words.
Three benefits over asking inline. The model choice is deterministic — this agent always runs on Haiku. The description lets Claude route to it automatically, so you stop having to remember to say "in a subagent." And the system prompt controls what comes back to the main session, which is the whole point.
One anti-pattern. It is tempting to define a fleet of subagents and have the main session orchestrate them to "sequence" a large task. Each one rebuilds its own prefix, none of them share context with each other, and you end up paying for the same codebase to be re-read several times. Keep task sequencing in a plan file and drive it yourself; use subagents for isolation, not for orchestration.
8. Choosing Model and Effort
8.1 What Anthropic says
The official guidance is short. Use smaller models for routine tasks and larger ones for complex or ambiguous tasks. Start at the default effort for each model and tune it as a general preference for the kind of work you do, not turn by turn. And when Claude gets something wrong, look at the context you gave it before you touch either setting — a vague prompt is fixed by a better prompt, not a bigger model.
There is also a diagnostic for which knob to reach for when context isn't the problem. If Claude had everything it needed, clearly tried, and still got it wrong, that is a capability gap: pick a more capable model. If it got it wrong by skipping a file, not running the tests, or abandoning a refactor halfway, that is an effort gap: raise the effort. Model is what Claude knows; effort is how hard it tries.
8.2 Two heuristics for the cost side
The guidance above is about quality. Two additions help with cost.
Look at the output share. A task that is mostly reading — codebase research, code review — tolerates an expensive model, because input is cheap and most of it is cached. A task that is mostly writing and thinking — implementing, debugging — amplifies model and effort cost through the 5x output multiplier.
Look at the rework risk. A small model's savings vanish the moment you need a retry, which costs another read-edit-test cycle. Use small models where a mistake is obvious at a glance; use big ones where it isn't.
8.3 A starting table
These are recommendations, not official guidance, and the effort column is a starting point to tune from, not a rule.
| Task | Model | Effort | Why |
|---|---|---|---|
| Codebase research, reading unfamiliar code | Sonnet | default | Input-heavy; analyse later on a bigger model if needed |
| Architecture, planning | Fable or Opus | high | Plan quality sets the cost of everything downstream |
| Executing a plan — mechanical changes | Sonnet | low–default | Files listed, steps known; thinking is wasted |
| Executing a plan — design judgment needed | Opus | default–high | |
| Bug with clear reproduction | Sonnet | default | Standard locate–fix–test loop |
| Intermittent or cross-module bug | Opus | high | Small models flail and burn turns |
| Writing tests | Sonnet | low–default | Pattern work |
| Reviewing your own PR | Opus | high | Read-only, small output; thinking is worth paying for |
| Reviewing team PRs at volume | Sonnet | default | Cost-sensitive at scale |
| Repetitive refactor or migration | Sonnet or Haiku | low | Let Opus set the pattern on file one |
| Docs, commit messages, PR descriptions | Haiku or Sonnet | low | Pure output; cheapest wins |
| Logs, test output, wide greps | Haiku, as a subagent | low | Large output, conclusion only |
| Security- or compliance-sensitive changes | Opus | high | Error cost is high; don't economise |
For subagent-heavy work, CLAUDE_CODE_SUBAGENT_MODEL routes every subagent to a named model while the main session stays on something larger.
8.4 Effort arithmetic [illustrative]
Effort controls the number of files read and tools called as well as thinking, so the following isolates only the thinking component to make the scale visible. Over forty turns, if high effort thinks around 3,000 tokens a turn and low around 300:
| Model | Low (~12k output) | High (~120k output) |
|---|---|---|
| Sonnet 5 | $0.12 | $1.20 |
| Opus 5 | $0.30 | $3.00 |
| Fable 5.1 | $0.60 | $6.00 |
In a long session, thinking output is the only line item that rivals cache reads. Anthropic publishes no per-level averages; treat these as order-of-magnitude.
9. The Workflow: Plan Big, Execute Small, Never Switch Mid-Session
Everything above converges on one pattern.
9.1 The pattern
Plan in one session, on a big model, at high effort. The output is a plan file — call it PLAN.md — that breaks the work into subtasks, each sized to fit one clean session: a few dozen turns, roughly ten files or fewer, and an explicit verification command that says when it is done. For each subtask, list the files involved, the dependencies on other subtasks, the gotchas discovered during planning ("the interface in X disagrees with its docs; the real signature is …"), and a recommended model and effort.
Execute each subtask in its own session. /clear, or open a new terminal. Start with @PLAN.md. Set model and effort for this subtask at the very start — this is the cheap moment — and do not touch them again.
Checkpoint at every green point. Commit. Update PLAN.md: what is done, what deviated from the plan and why. The next session reads the plan and gets both the intent and the current state, without depending on a compaction summary to carry either.
Exit rule. Every session, whether it ends because the subtask is done or because you ran out of budget, ends the same way: commit, update PLAN.md. A budget running out mid-task stops being an emergency and becomes an early end to one session.
9.2 Case: plan on Fable, execute on Sonnet [illustrative]
Suppose the planning session reaches 80,000 tokens and you want to execute on Sonnet. There are three ways to make the switch.
Bare /model. Sonnet re-prefills all 80,000 tokens at 2x — about $0.32, once — and then every execution turn carries 80,000 tokens of planning noise. It works. It is the most expensive option.
/compact, then /model. Compact on Fable while the cache is warm (reading the 80,000 is $0.02; writing a summary is roughly $0.15). The conversation is now about 10,000 tokens. Switch to Sonnet: the re-prefill is $0.04, and every execution turn reads 10,000 instead of 80,000. Never the other order — that is a full-size rewrite followed by a second one.
Plan to file, /clear, new session. Have Fable write PLAN.md, clear, start Sonnet with @PLAN.md. Cheapest, and the execution context contains nothing but the plan. The one requirement is that the plan be self-contained: paths, discovered gotchas, verification commands, no "as discussed above."
And the comparison that justifies switching at all — thirty execution turns, each adding about 1,500 tokens and producing about 500:
| Stay on Fable | Switch to Sonnet | |
|---|---|---|
| Switch cost | — | $0.32 |
| New tokens written | $0.90 | $0.18 |
| Output | $0.75 | $0.15 |
| History reads | ~$0.77 | ~$0.61 |
| Total | ~$2.42 | ~$1.26 |
The switch pays for itself within ten turns and the gap widens from there. Switch once; do not bounce between plan and execute in the same session.
9.3 Why state lives in files
Anthropic's engineering guidance on agent design describes structured note-taking — an agent maintaining a NOTES.md outside its context window — as persistent memory with minimal overhead: it survives compaction, it survives /clear, and it costs a few hundred tokens to write. PLAN.md and PROGRESS.md are that pattern applied to your own workflow. The conversation is working memory. Files and git are the record.
10. Measuring It
In the session. /cost on an API key and /usage on a subscription show session-level figures, and the status line can display running totals. Both report at list price by default; if your organisation has contracted rates, the modelPricing managed setting aligns the display with the bill.
Across sessions. Claude Code writes usage to local JSONL logs. ccusage parses them into daily, monthly, and per-session reports, including cache-write and cache-read breakdowns — which is exactly what you need to check your sessions against the 84% benchmark from Section 2.
Across a team. Set CLAUDE_CODE_ENABLE_TELEMETRY=1 and Claude Code exports OpenTelemetry metrics — tokens by type, cost by model, tool activity — to whatever collector you already run. Grafana, SigNoz, and Datadog all have community dashboards for it. This is the only option that gives per-developer figures in near real time regardless of provider.
For calibration: across enterprise deployments Anthropic reports an average of around $13 per developer per active day and $150–250 per developer per month, with 90% of users under $30 on any given day.
In the API response. If you build on the API directly, read cache_creation_input_tokens and cache_read_input_tokens alongside input_tokens. The last is only the uncached remainder; a request showing 500 input tokens and 90,000 cache-read tokens is a healthy one.
11. Checklist
Starting a session
-
/contextin a fresh session. Trim CLAUDE.md;/mcpoff anything you won't use today. - Confirm
/modeland/effortdeliberately — both persist from last time — then leave them alone. -
@-mention the files you already know matter. Once each.
During
- Quiet flags on noisy commands, in CLAUDE.md. Big outputs to a subagent.
- At the end of each turn: continue, rewind, clear, compact, or subagent — based on how much of the context the next step actually needs.
- Commit at green points. Progress to a file, not to the conversation.
Before a break or a switch
-
/compactwhile the cache is hot, with instructions about what to keep. - Then — and only then — change model or effort if you must.
Between tasks
-
/rename, then/clear.
Every one of these comes down to the same idea. The tokens you pay for should be the tokens spent on your task — not on a system prompt you forgot to trim, not on a test log from forty turns ago, not on re-prefilling a conversation because you changed a setting at the wrong moment. Get that right, and cost stops being something you worry about and becomes something you can predict.
12. Tools That Claim to Save Tokens
The community has produced a small industry of add-ons that promise to cut Claude Code token use — often by 60% or more. Two of them, rtk and caveman, have become popular enough that JetBrains ran paired A/B benchmarks on both in mid-2026. The results are the most useful thing in this section, because they show the gap between what a tool measures about itself and what it does to your bill.
The frame for evaluating any of them is the per-turn formula from Section 2.3. Every tool attacks exactly one term:
history × 0.1 × input_price (cached reads) + new_tokens × 2 × input_price (fresh writes: tool output, files) + output × output_price (prose, thinking)
— or it attacks the price itself, by routing to a different model. Knowing which term a tool targets tells you, before you install it, whether it can matter for your workload.
12.1 rtk — compressing command output
What it is. A Rust CLI proxy. A PreToolUse hook rewrites eligible Bash commands to rtk <command>; rtk runs the real command and hands Claude a filtered version of the output — git status becomes three lines instead of eleven, a 200-line failing cargo test becomes twenty. It supports 100+ commands, including ./gradlew and mvn with dedicated filters, adds under 10 ms per call, and the hook means every session and subagent gets it without per-command instructions. rtk gain reports cumulative savings.
Which term it targets. Fresh writes — specifically Bash tool output. It does nothing to Read, Grep, or Glob, which are Claude Code's built-in tools and bypass the hook entirely. The project's own documentation is careful about this: its percentages measure bash output bytes, not your bill, and it estimates tokens as bytes ÷ 4.
Claimed. 60–90% reduction in command output.
Measured. JetBrains ran rtk v0.43 against a control on 86 SkillsBench tasks with Claude Code pinned and Sonnet 5 at two effort levels. At high effort: no measurable cost difference. At low effort: rtk sessions were 7.6% more expensive (p = 0.004). Task quality was unchanged in both arms. The compression itself is real; the reason it did not translate to savings is that most tokens in an agentic session are not Bash output, and where rtk did drop a line the model sometimes re-ran the command or read the file raw.
Risks. Editorial. A filter that summarises test output is deciding what the model needs to see. When it drops the one line that mattered, the agent either spends turns recovering or, worse, declares a failing build green. Also a name collision — there is an unrelated Rust project called rtk; verify with rtk gain.
The git problem specifically. Git is where the editorial risk has bitten hardest, because git's output is mostly signal rather than bulk, and rtk's filters were tuned for bulk. Three failure modes are documented in the project's own issue tracker. First, filtering strips the To <repo> confirmation line from git push; the agent, seeing no success marker, treats the push as hung and re-runs it in the background — one report describes fifteen minutes of retries on a push that had succeeded on the first attempt. Second, rtk's caching layer has served stale repository state after a write happened outside its view — git status reporting a clean tree that wasn't — and the bug was present even through rtk proxy, the documented raw-execution escape hatch, because the cache sat above the bypass. Third, Claude Code's worktree-isolated sessions refuse any rtk-wrapped git command outright, since the isolation check can no longer see which directory git will act on; every variant, including rtk proxy git status, gets the same refusal.
None of these are fatal, and the project has responded — a proposed signal-vs-bulk classifier would route git, gh, and glab output through unfiltered by default. Until that lands, the practical escape hatches are: RTK_DISABLED=1 git push for a single command; an exclude_commands list in ~/.config/rtk/config.toml (a pattern like "git push" matches git push origin main); and rtk proxy <cmd> for raw execution, with the caveat above about the cache. If you adopt rtk, excluding git push, git pull, git fetch, and git merge on day one is cheap insurance. The hook is designed to fail open — any error path exits 0 and the command runs unmodified — so a broken rtk install degrades to no compression rather than a blocked command.
When it helps. Shell-heavy workflows on noisy toolchains — Gradle, Maven, npm install, verbose test runners — where you have not already put quiet flags in CLAUDE.md. If you have, most of the gain is gone. It does not help sessions dominated by file reads.
12.2 caveman — terse output
What it is. A skill that instructs Claude to answer in compressed, telegraphic prose — "why use many token when few do trick" — while leaving code, commands, and file paths byte-exact. Three intensities (lite, full, ultra), one-line install across 30+ agents, and a set of companions: caveman-commit for terse commit messages, caveman-compress for shrinking CLAUDE.md and memory files (~46% claimed), and caveman-shrink, MCP middleware that compresses tool descriptions before they enter context.
Which term it targets. Output — assistant prose only. Not thinking, not tool output, not files. The project states this plainly.
Claimed. 65% fewer output tokens (revised down from 75%).
Measured. JetBrains, 82 paired tasks, Claude Code 2.1.200: 8.5% fewer output tokens, roughly 10% of cost, no detectable quality change. An early small run showed 29.5% and did not replicate. The project's own README now publishes these numbers alongside a separate result: on chat-style Q&A against a plain "answer concisely" control, 50% fewer output tokens at the median. Both are true. In agentic coding, most output is code and tool calls the skill never touches; in conversation, prose is most of the output and the cut is large.
The hidden cost. The skill injects its rules every turn — the project's own stats tool estimates about 1,250 input tokens per turn of overhead and reports a net figure. On short, terse exchanges that net goes negative: you pay more in rule input than you save in prose output. The project says so directly, which is to its credit.
Risks. Readability when you actually need the explanation — ultra in particular. Transcripts that read as rude if shared with people who didn't opt in. A six-line "be concise" instruction in CLAUDE.md gets a meaningful fraction of the benefit for free.
When it helps. Conversational and review-heavy use, where you read a lot of Claude's prose. Marginal in agentic sessions.
12.3 Model routers and gateways
Tools such as claude-code-router, LiteLLM, and 9Router sit between Claude Code and the API, routing requests by rule — background tasks to Haiku, long contexts to a large-window model, some workloads to a different provider entirely. Some bundle rtk-style compression.
Which term they target. The price. Nothing about token volume changes; the multiplier does.
Trade-offs. This is the only category that can cut cost by a large integer factor, and for API-key users with a clear split between mechanical and hard work it is worth a look. But routing decisions are made by a rule, not by you, so the "never switch mid-session" discipline from Section 3 is now delegated to a config file that may re-prefill your conversation on a different model without asking. Subscription users generally cannot use them at all. And any gateway that sends code to a third-party provider is a data-handling decision, not a cost one — check that before installing. The built-in equivalents — /model at session start, CLAUDE_CODE_SUBAGENT_MODEL, per-subagent model: in frontmatter — cover most of the legitimate use without the indirection.
12.4 Codebase-index MCP servers
A cluster of tools (claude-context, ContextCore, SDL-MCP, various "search instead of read" servers) index your repository into embeddings or a symbol graph and expose an MCP search tool, so Claude retrieves the relevant few hundred lines instead of reading whole files. Claims run to 90%+.
Which term they target. Fresh writes — file content entering context.
Trade-offs. None have an independent benchmark comparable to the JetBrains runs. Each one adds its tool schemas to your baseline context on every turn, which is the exact cost Section 4.1 tells you to trim. Claude's own Grep and Read are already precise when the prompt is; a good @-mention beats a semantic search that returns the wrong chunk. Worth trying on very large monorepos where exploration genuinely dominates; skeptical otherwise.
12.5 ccusage — not a saver, but start here
ccusage parses Claude Code's local JSONL logs into daily, monthly, and per-session reports with cache-write and cache-read breakdowns, and ccusage report --compare shows deltas between periods. It saves nothing. It is nonetheless the first thing to install, because every number in this section — including the vendors' — is meaningless against your workload until you have a baseline. Run a normal week first, then add tools one at a time.
12.6 The built-ins these tools compete with
Before any of the above, the free versions:
| Term | Built-in lever | Third-party equivalent |
|---|---|---|
| Fresh writes (tool output) | Quiet flags in CLAUDE.md; BASH_MAX_OUTPUT_LENGTH; a subagent for noisy jobs |
rtk |
| Output (prose) | A concise-style instruction in CLAUDE.md; lower /effort
|
caveman |
| Baseline (schemas, rules) |
/context to see it; /mcp to disable; skills instead of CLAUDE.md |
caveman-shrink, MCP lazy-loaders |
| Fresh writes (files) |
@-mentions; precise prompts; Grep before Read |
codebase-index servers |
| Price |
/model at session start; CLAUDE_CODE_SUBAGENT_MODEL; subagent model:
|
routers and gateways |
12.7 Summary
| Tool | Targets | Claimed | Independently measured | Overhead | Verdict |
|---|---|---|---|---|---|
| rtk | Bash output | −60–90% output bytes | 0% (high effort) to +7.6% cost (low effort); quality flat | <10 ms/call; hook | Try on noisy toolchains without quiet flags; exclude git push/pull/fetch/merge; measure |
| caveman | Assistant prose | −65% output tokens | −8.5% output in agentic work; ~−50% in chat Q&A | ~1,250 input tokens/turn | Chat and review use; marginal for coding |
| caveman-compress / -shrink | CLAUDE.md, MCP schemas | −46% on files | none | one-time | Reasonable if your baseline is large |
| Routers / gateways | Price | varies | none comparable | proxy, config | API users with clear task split; check data handling |
| Codebase-index MCP | File reads | −90%+ | none | schemas every turn | Large monorepos only; skeptical |
| ccusage | — | — | — | none | Install first |
The pattern across all of it: the tools measure the thing they compress and report that as savings. Your bill is the formula. Compressing a term that is 5% of the formula by 80% saves 4%. Measure your own sessions, find the term that actually dominates, and reach for the built-in lever first.
References
Anthropic
- Hallie, L. "Maximizing the value of your Claude Code sessions." claude.com blog, August 2026. https://claude.com/blog/maximizing-the-value-of-your-claude-code-sessions
- Hallie, L. "Choosing a Claude model and effort level in Claude Code." claude.com blog, July 2026. https://claude.com/blog/claude-model-and-effort-level-in-claude-code
- "Pricing." Claude Platform Docs. https://platform.claude.com/docs/en/about-claude/pricing
- "Prompt caching." Claude Platform Docs. https://platform.claude.com/docs/en/build-with-claude/prompt-caching
- "Optimizing for cost and intelligence." Claude Platform Docs. https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence
- "Best practices for Claude Code." Claude Code Docs. https://code.claude.com/docs/en/best-practices
- "Create custom subagents." Claude Code Docs. https://code.claude.com/docs/en/sub-agents
- "Manage costs effectively." Claude Code Docs. https://code.claude.com/docs/en/costs
- "Effective context engineering for AI agents." Anthropic Engineering. https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
Community and third-party
- shanraisshan, claude-code-best-practice. https://github.com/shanraisshan/claude-code-best-practice — turn-end decision framework, compact-with-hint, subagent test.
- DataCamp, "Claude Code Best Practices." https://www.datacamp.com/tutorial/claude-code-best-practices — document-and-clear pattern,
CLAUDE_CODE_SUBAGENT_MODEL. - Build This Now, "Claude Code Prompt Caching." https://www.buildthisnow.com/blog/guide/development/claude-code-prompt-caching — subscription TTL behaviour.
- ryoppippi, ccusage. https://github.com/ryoppippi/ccusage
- SigNoz, "Claude Code Monitoring with OpenTelemetry." https://signoz.io/blog/claude-code-monitoring-with-opentelemetry/
Token-saving tools (Section 12)
- JetBrains AI, "Does Speaking to Agents Like Cavemen Really Save 65% of Tokens? We Test." July 2026. https://blog.jetbrains.com/ai/2026/07/speak-to-ai-agents-like-cavemen-tosave-tokens/
- JetBrains AI, "rtk Claude Code Token Savings: A Skill Trial Benchmark." July 2026. https://blog.jetbrains.com/ai/2026/07/rtk-claude-code-token-savings/
- rtk-ai, rtk — Rust Token Killer. https://github.com/rtk-ai/rtk — README, CLAUDE.md (scope notes on Bash-only hook and byte-based estimates);
hooks/README.md(fail-open design,RTK_DISABLED,exclude_commands); issues #2121 (git push marker stripped), #2148 (stale state throughrtk proxy), #3864 (worktree isolation refusal). - JuliusBrussee, caveman. https://github.com/juliusbrussee/caveman — README benchmarks;
caveman-statsrule-overhead estimate. - Pillitteri, P. "Claude Code Token: 10 GitHub Repos That Cut Up to 90%." April 2026. https://pasqualepillitteri.it/en/news/1181/claude-code-token-10-github-repos-savings — baseline-first methodology.
- ComputingForGeeks, "Reduce Claude Code Tokens: 10 Tested Tools." April 2026. https://computingforgeeks.com/reduce-claude-code-token-usage-tools/
Worked examples marked [illustrative] use the list prices in reference 3 with assumed token counts; they are the author's own and should be read for their ratios, not their absolute values.
Top comments (0)