Each bar is one API call. Its length is the context it sends.
system prompt + toolsconversationtest log
Log re-sent0 tokens
Illustration: a 12k-token test log read at call 3 of a 24-call session.
−32%cost over 80 A/B runs in Claude Code (Sonnet 5)
40/40runs passed, with and without the rules
−51%on the task held out from tuning the rules
One log, paid on every call.
The agent re-sends its whole context with each request. Whatever it reads early is billed again and again until the session ends or compacts. Try your own numbers.
55 later calls re-send it.
That one read costs as much as 6.75 fresh reads of the same text.
Bounded to 800 tokens with tail -n 40, it would cost 87% less.
Claude pricing ratios: cache write 1.25×, cache read 0.1× of fresh input.
See your own leaks in one command.
The audit reads your Claude Code and Codex transcripts on your machine and prices every oversized read, noisy log and wasted round-trip by its estimated context tax.
Local and read-only. No network, no telemetry.
One Python file, standard library only.
Shows what your CLAUDE.md costs on every call.
tokenleak suggest turns a project's leaks into rules for its CLAUDE.md.
--html writes a shareable report; --redact hides commands, paths and project names.
~/my-project
$python3 tokenleak.py --since 30dtokenleak 1.5.1 · 20 sessions (20 Claude Code) · 156 API calls · since the beginning context processed 11.1M tokens (cache reads 10.4M · writes 757.6k · fresh 312) output cost split context 93% (cache reads 38% · writes and uncached 55%) output 7%LEAK SCORE15.8% grade C% of token cost that was avoidable · A<5 B<10 C<20 D<30 leak count avoidable of cost fix big-read 17 153.2k 13.7% Locate, then read: grep -n first, then read o wide-search 4 11.4k 0.9% Narrow searches: scope path/type, cap results noisy-shell 4 10.0k 0.9% Bound every command: quiet flags, `> log; tai serial-call 1 - 0.3% Batch independent reads/searches in one turnalways loaded ~43% of cost 52.2k tok at session start (system prompt, tools, MCP), re-setop leaks 1 1.0% big-read Read ./shopcart/catalog.py 11.6k tok × 10 l 2 1.0% big-read Read shopcart/catalog.py 11.6k tok × 9 la 3 0.9% big-read Read shopcart/catalog.py 11.6k tok × 8 la 4 0.9% big-read Read shopcart/catalog.py 11.6k tok × 7 la 5 0.9% big-read Read shopcart/catalog.py 11.6k tok × 6 la
Real output: the audit of 20 benchmark sessions run without the rules.
Rules for the agent. Numbers for you.
The rules
About 770 tokens that change what the agent asks for.
Locate, then read. Size first, grep, read the range.
Compute, don't read. Data questions get a one-liner.
Bound every command. Log to a file, tail it, grep it.
Never re-read what is already in context.
Batch independent calls in one turn.
Diffs over files.git diff --stat first.
Edit, don't rewrite.
Narrow searches and fetches.
Delegate wide exploration to a subagent.
Answer lean. Result first, no recap.
The rules forbid saving tokens by hiding the real error, guessing a file, or skipping tests.
Live leak meter
Your current session's score, right in the Claude Code status line.
leak 3.1% A· ctx 84.2k · top big-read
Before and after
Compare your leak score and cost per call around the day you installed it.
tokenleak --compare 2026-10-01
Everywhere the agent works
In Claude Code the plugin loads the rules at session start, after every compaction and in every subagent, and stops whole reads of big files. Codex gets the rules at session start.
Works with any agent that reads skills
Measured, not promised.
Same prompt, a fresh copy of the same repo for every run, ten runs per task and arm in two batches. The only difference is the rules in the system prompt. A script checks every result.
Sum of medians, 4 tasks
$1.07→$0.73
−32% cost
Without the rulesWith tokenleak
Cost per run in Claude Code (Sonnet 5), as reported by Claude Code. Small dots are single runs, large dots are medians of 10.View as table
Task
Without
With tokenleak
Change
Passed
Two batches on the same day gave −40% and −21%: runs vary a lot, so these are medians of 10. The rules were piloted first and adjusted once; the feature task was written beforehand and never used for tuning.
On Haiku 4.5 the rules alone changed nothing (−1%): small models follow them less. The plugin’s read guard, which stops whole reads of big files, brought it to −20% (and −28% with v1.5’s outline, in a second batch). Four small tasks on a synthetic repo: run the audit on your own sessions.
Every run, the exact rules used and the harness are in the repo.
Install in one step.
Pick your setup. MIT licensed, nothing to configure.
Plugin: rules in every session and subagent, a read guard for big files, and the /tokenleak skill.
Not in the benchmark: 40 of 40 runs passed in both arms on Sonnet 5, and every run in both Haiku 4.5 batches, each checked by a script. The rules forbid saving tokens by guessing a file, hiding the error or skipping verification.
Isn't shorter output enough?
Output is the small part of the bill in agentic coding. In the benchmark runs without tokenleak, everything the model wrote (replies, tool calls, thinking) was 7% of the cost on Sonnet and 10 to 11% on Haiku; the rest was context. tokenleak works on what enters the context, and the audit shows the split on your own sessions.
How accurate is the audit?
Session token totals come from the usage the transcripts record. The size of each tool result is estimated at about four characters per token, and "avoidable" only counts what exceeds a sane budget. It is an estimate: the audit can't know whether a big read was truly needed, so read each finding as a suspect and judge the trend with --compare.
ccusage or tokenleak?
Both read the same local transcripts. ccusage tells you how much you spent, by day, session or model. tokenleak tells you which tool results made it expensive and plugs them, with rules and a read guard. They work well side by side.
What about rtk, caveman and the rest?
They complement it. rtk compresses command output at the shell level and output-style skills shorten replies. tokenleak changes what the agent asks for and measures the result. Run the audit before and after anything you install.
Does anything leave my machine?
No. The audit reads files under ~/.claude/projects and ~/.codex/sessions, plus your CLAUDE.md and AGENTS.md to size them, and prints a report (or writes one with --html). It makes no network calls; the source is one readable Python file.
