Field notes: what actually saves tokens

TL;DR. The popular token-saving tools work, but the headline percentages are per-command best cases, not what your bill drops by. RTK cuts 50 to 90 percent on noisy commands yet often single digits across a real session, because incompressible source reads dominate the total, and it can increase cost when its lossy output makes the model take more turns. Output-side tools (caveman, a terse CLAUDE.md) cut the expensive half but cost input tokens every turn, so they only net out at high output volume. The prompt cache is real and automatic but is isolated per organization with a 5-minute time-to-live (refreshed on each use, one hour optionally); you cannot "share" it, you engineer a stable prefix so consecutive sessions reuse it. This chapter validates each claim with measurements and ends with a company rollout.

Contents

• The tools, honestly rated
• RTK: how the savings are measured, and why yours is lower
• Is RTK stable? The more-turns problem
• Cutting the expensive output side
• Compress your CLAUDE.md to under 500 tokens
• Caching across sessions: what you can and cannot share
• A company rollout
• Further reading
• Takeaways

The previous three chapters were how Claude Code works. This one is the questions a team actually asks once they start optimizing: which tool saves what, how is it measured, is it stable, and how do we roll this out without making things worse. Every number here is either measured on the build machine or pulled from the tool's own benchmarks and issue tracker, and labeled as such, because the gap between the marketing percentage and the realized one is the whole lesson.

The tools, honestly rated

Four tools come up constantly. They cut different sides of the bill, and conflating them is the first mistake.

Don't be confused. RTK and Headroom cut the input side (the tool output and context the model reads). caveman and a terse CLAUDE.md cut the output side (what the model writes). Output costs about five times input per token (Chapter 2), so the output tools have higher per-token leverage, but they cost a few input tokens every turn to buy it. Which one helps you depends on whether your sessions are read-heavy or write-heavy. Measure with /usage before you choose.

RTK: how the savings are measured, and why yours is lower

This is the question behind "RTK says 60% but I see 27%." Both numbers are real; they measure different things.

RTK computes savings per command with a simple formula: savings = (1 − tokens_with_RTK / tokens_without_RTK) × 100. It runs a command both ways and compares. Across the project's published benchmark of more than 2,900 commands it reports about 89% of CLI noise removed, with a wide per-command spread: roughly 92% on cargo test, 81% on git status, 78% on find, and 50% on grep. The spread is the point: the savings depend entirely on how much noise a command's output carries.

Here is the same measurement on this book's own repository, run on the build machine (real, not illustrative):

RTK per-command savings (chars as a token proxy):
  git status             raw     100 -> rtk      49   saved 51.0%
  git log -20            raw   25527 -> rtk    6790   saved 73.4%
  find *.md              raw    9949 -> rtk    1263   saved 87.3%
  grep -rn ctx           raw   64996 -> rtk   25781   saved 60.3%

rtk gain (its own token accounting, across the whole session):
  Total commands:  11
  Input tokens:    365.7K
  Tokens saved:    23.9K  (6.5%)

Read those two blocks together and the 60-versus-27 mystery dissolves. Per command, RTK saved 51 to 87 percent, right in the advertised range. Across the session, rtk gain reported only 6.5 percent saved. The reason is in the session: one command read a 1.3 MB generated file, which RTK passed through unchanged because there was no noise to strip, and that single incompressible read was a third of a million tokens, swamping the savings from the noisy commands. The realized percentage is the savings on compressible commands diluted by all the incompressible tokens in the session, mostly source-file reads. A session that is heavy on tests and git will land near the headline; a session that is heavy on reading source files (which is most coding) will land far below it. Both 60% and 27% are honest; they are different denominators.

To measure your own realized number, do not trust the per-command figure. Run rtk gain for the token accounting and rtk cc-economics for the Claude Code spending-versus-savings view, and bracket a real task with /usage before and after. That realized number, not the marketing one, is what your bill follows.

Remember. A compression tool's headline percentage is measured on the output it can compress. Your bill is set by your whole token mix, including everything it cannot. Always measure the realized saving on a real workload, never the per-command best case.

Is RTK stable? The more-turns problem

The concern that "RTK is not stable, it causes more turns because the model dislikes the transformed output" is correct, documented, and worth taking seriously. It is the lossy-compression failure mode from Chapter 3 and Chapter 11, showing up in production.

Three concrete failure modes are on the project's own issue tracker and in independent benchmarks:

• Silent truncation. RTK can truncate output without signaling it, so the model decides on incomplete data and does not know it is incomplete (issue #827). A diff cut in half can send the agent down a wrong path.
• Corruption when piped. When RTK rewrites a command whose output is piped or redirected into another program, its compact human-readable format corrupts the downstream consumer; fed to a subagent, the subagent gets garbage and produces confidently wrong output (issue #1282).
• Net cost can rise. One independent benchmark of 20 alternating runs found RTK won 10, raw won 6, and 4 tied, and another reported the RTK hook increasing Claude Code cost by about 18%. The mechanism is exactly the worry: when the compressed output drops something the model needed, the model re-runs the command or re-reads the file, and the extra turn costs more than the compression saved.

The takeaway is not "do not use RTK." It is "use it where compression is safe and measure the net." Scope it to genuinely noisy commands whose detail the model does not need verbatim (test summaries, git status, find), never let its output be piped into another tool or a subagent, never point it at source files the model must read precisely, and judge it by rtk cc-economics and /usage over a real task, not by per-command savings. Treated as a selective filter it helps; treated as a blanket hook over every command it can cost more than it saves.

Don't be confused. "Tokens saved on a command" and "money saved on the task" are different numbers and can have opposite signs. Lossy compression that triggers one extra model turn can erase the savings of dozens of compressed commands, because a turn re-sends the whole context (Chapter 17). The only honest scoreboard is end-to-end cost on a real task.

Cutting the expensive output side

Output is billed at about five times input, and unlike input it cannot be cached, so trimming it is high-leverage. Two tools target it.

caveman is a Claude Code skill that forces a terse, fragment-style output ("why use many token when few token do trick"). It reports about 65% average output reduction across its sample, in a 22 to 87 percent range, and it only touches output: the model's internal reasoning and the code it writes are untouched, only the narration around them shrinks. It auto-activates per session in Claude Code, or you invoke /caveman, with levels from lite to ultra.

claude-token-efficient (the drona23 repo) is the same idea as a drop-in file: a CLAUDE.md of terse-output rules ("Read files first. Write complete solution. Test once. No over-engineering," skip preambles and closing fluff, prefer targeted edits). You install it by fetching the file:

curl -o CLAUDE.md https://raw.githubusercontent.com/drona23/claude-token-efficient/main/CLAUDE.md

Its own benchmark is refreshingly honest about the catch: 63% output reduction on a directional test, but only 4 to 12 percent real output-token savings depending on the model, and because the rules file adds input tokens on every turn, the net is positive only when output volume is high. That is the general law of output-shaping instructions: you pay a small, constant input tax (the rule sits in the cached prefix, Chapter 17) to save a variable output amount, so it wins on write-heavy work and can lose on read-heavy work. The provider's own effort lever (Chapter 4), lowered with /effort for routine tasks, does the same thing without the input tax, which is why it is the first output control to reach for.

Compress your CLAUDE.md to under 500 tokens

A recurring, correct piece of advice is to refine any project or system CLAUDE.md down to a few hundred tokens. The reason is mechanical: CLAUDE.md sits in the cached prefix but is re-read on every turn, so its size is a baseline you carry all session (Chapter 17), and a short, stable file is also more likely to clear the cache's minimum-prefix bar cleanly and to be followed reliably (the docs note adherence drops past about 200 lines).

First, measure. This book's own CLAUDE.md, on the build machine:

CLAUDE.md:  139 lines, 1035 words, 7603 chars
  ~tokens (words x 1.3): 1345
  ~tokens (chars / 4):   1901

So it is roughly 1,300 to 1,900 tokens, three to four times a 500-token target. Getting it down is not deletion, it is moving each line to where it belongs (Chapter 19's "what goes where"):

1. Keep only always-true facts as imperatives. "Build with make," "tests in tests/," "never push to main." One line each, no prose.
2. Move procedures to skills. A multi-step "how to cut a release" is a skill that loads on demand, not lines in CLAUDE.md that load every turn.
3. Move path-specific rules to .claude/rules/ with a paths: glob, so they load only when matching files are touched.
4. Put human notes in HTML comments. Block-level <!-- ... --> comments are stripped before the file enters context, so maintainer notes cost zero tokens.
5. Import the rest. Pull long reference material in with @path so the main file stays scannable.

Then re-measure with the same count. A useful discipline is to treat 500 tokens as a budget the project CLAUDE.md may not exceed, and to review it whenever it grows, the same way you would review any always-on cost.

Caching across sessions: what you can and cannot share

The claim worth validating carefully: "if you use it a long time it saves more, most work is reading or generating code, and if you open the cache across sessions and keep the code optimized it works well. How do you share the cache?" Here is what is true, against the provider's caching documentation.

• The cache is automatic, not shared by hand. Prompt caching keys on the organization (and, as of early 2026, the workspace) plus a byte-identical prefix. The docs are explicit: caches are isolated between organizations and never shared across them, even with identical prompts. There is no knob to "share a cache" with another prefix or another org. You do not share it; you arrange for the same prefix to recur.
• The lifetime is short but self-renewing. A cache entry lives 5 minutes by default, and the timer refreshes for free every time the entry is used. So within an active session, every turn reuses and re-arms the cached prefix, which is exactly why "use it a long time saves more": a long, continuous session keeps the prefix warm and pays full price for it only once. For gappy work there is a 1-hour option (at twice the write cost) that spans longer pauses.
• Across sessions, reuse is real but conditional. If you start a new session with the same prefix (same system prompt, tools, and CLAUDE.md) within the time-to-live of the last use, in the same organization and workspace, the new session reads the still-warm cache. That is the closest thing to "sharing across sessions," and you get it by keeping the prefix byte-stable, not by any explicit action. Edit CLAUDE.md between runs and the prefix changes, so the next session pays a fresh write.
• Reading versus generating code. Reading code is input, but a file's contents sit in the volatile tail, not the cached prefix, so they are not reused unless you re-send the identical bytes. Generating code is output, which is never cached. So caching helps the stable instruction-and-tool prefix, not the specific files you read or write. The "optimize the code and it caches well" intuition is half right: a stable codebase and stable instructions make a stable prefix, and the more you hold constant, the more the cache pays, but the variable file contents of each task are not what caches.

Remember. You do not share a prompt cache; you engineer a stable, recurring prefix and let the automatic cache reuse it within its time-to-live. Long continuous sessions and byte-stable CLAUDE.md files are how you "keep the cache open"; editing the prefix is how you accidentally throw it away.

A company rollout

Putting this into a team is a sequence, and the order matters because each step makes the next one measurable. This is the capstone workflow at organization scale.

1. Baseline before you change anything. Have a pilot group run normal work for a week and record /usage and rtk gain. The published reference is about $13 per developer per active day; find your own number so later changes are measurable, not anecdotal.
2. Standardize the instruction layer. Ship an organization CLAUDE.md at the managed-policy path for non-negotiable rules (Chapter 18), keep each project CLAUDE.md under a 500-token budget, and move path-specific guidance to shared .claude/rules/. Commit them so the whole team inherits the same lean context.
3. Make prefixes cache-friendly. Train the team not to churn CLAUDE.md mid-session, order tools and system content stably, and use the 1-hour cache for long-running automation. This is free money once the instruction layer is stable.
4. Apply output discipline where it pays. Default to lower /effort for routine work; adopt a terse-output rule or caveman on the write-heavy workflows where output volume, not reading, dominates the bill. Measure that it nets positive.
5. Compress tool output selectively. Use a PreToolUse hook (or RTK) to filter genuinely noisy commands, never piped output or source reads, and gate the rollout on rtk cc-economics showing a net win. Prefer plain CLI tools over MCP servers for context efficiency.
6. Delegate and right-size models. Send verbose reads to subagents so their output stays out of the main window, and set cheap subagents to model: haiku, teammates to Sonnet, and reserve Opus for the hard main-thread reasoning.
7. Let memory and learning compound. Keep auto memory on so each repo gets smarter, and codify recurring corrections into CLAUDE.md (Chapter 12) so the same mistake is not re-paid for across the team.
8. Govern with managed settings. Use managed settings for permission denies, spend caps (--max-budget-usd in automation), and the per-user rate limits the cost documentation recommends by team size.
9. Re-measure and iterate. Compare /usage against the week-one baseline. Keep what moved the realized number; drop what only looked good per command.

Done in this order, a company gets the compounding wins (a lean shared instruction layer, warm caches, disciplined output, selective compression, right-sized models) and avoids the traps that make costs rise: a blanket RTK hook, a bloated CLAUDE.md, churned prefixes, and output tools applied to read-heavy work.

Further reading

• RTK benchmarks and savings methodology (rtk-ai.app/benchmarks, github.com/rtk-ai/rtk): the per-command numbers and the (1 - on/off) formula, plus the open issues on truncation and pipe corruption (#827, #1282).
• caveman (github.com/JuliusBrussee/caveman) and claude-token-efficient (github.com/drona23/claude-token-efficient): the two output-shaping approaches, with their own honest benchmarks.
• Headroom (github.com/chopratejas/headroom): the programmatic compression layer, CacheAligner, and headroom learn.
• Anthropic prompt caching (platform.claude.com/docs/en/build-with-claude/prompt-caching): the authoritative word on time-to-live, refresh-on-use, organization and workspace isolation, and the per-model minimum prefix.
• Claude Code, "Manage costs effectively" (code.claude.com/docs/en/costs): the per-developer cost baselines, rate-limit recommendations, and the hook-based output-filtering pattern.

Takeaways

• A tool's headline percentage is its best case on compressible output; your realized saving is that diluted by everything it cannot compress. On this repo, RTK saved 51 to 87 percent per command but 6.5 percent across a source-read-heavy session. Measure the realized number with rtk gain, rtk cc-economics, and /usage.
• RTK's instability is real and documented (silent truncation, pipe corruption, an independent benchmark showing net cost up about 18%). Lossy output that causes one extra turn can cost more than the compression saved. Scope it to safe noisy commands and judge it on end-to-end cost.
• Output tools (caveman, terse CLAUDE.md) cut the expensive five-times side but cost input every turn, so they net out only on write-heavy work. The effort lever cuts output without the input tax.
• Refine CLAUDE.md to a 500-token budget by keeping only imperative facts and moving procedures to skills, path rules to .claude/rules/, and human notes to HTML comments. Measure before and after.
• You cannot share a prompt cache; it is organization and workspace isolated with a 5-minute refresh-on-use lifetime (one hour optionally). Long continuous sessions and byte-stable prefixes are how you keep it warm across turns and sessions.

👉 That is the practitioner's view: the claims, validated, and a rollout without the traps. The next chapter turns the lens on your own telemetry, dissecting a real /usage and /context readout field by field so you can diagnose a session at a glance. Continue to Reading the gauges.