tokenleak

Overview

Every tool result an agent pulls into context is re-sent on every later call until compaction, so a 6k-token log read early in a 60-call session is paid about 55 more times. These rules make the agent let in only what the next decision needs: locate before reading, compute instead of reading data, bound command output, never re-read, batch independent calls. Over 80 A/B runs in Claude Code (Sonnet 5) they cut cost by 32% with the same 40/40 pass rate; on Haiku 4.5 they only help together with the plugin's read guard (-20%). Method and raw results are in the source repo.

When to Use This Skill

• Use on coding tasks that read files, run tests, builds or installs, use git, or search a codebase.
• Use when the user wants to save tokens, reduce cost, or stay under usage limits.
• Use when a session keeps hitting compaction because tool output fills the context.

Rules

1. Locate, then read. Don't know a file's size? Check it (wc -l) along with your first search. Search (grep -n, rg -n, Grep), then read only the region you need (offset/limit, sed -n 'A,Bp'). Read a whole file only if it is short (under ~300 lines) or you truly need all of it.
2. Compute, don't read. For questions about data (counts, totals, filters, lookups in big data files, CSV, JSON, logs), run a short script or one-liner that prints only the answer. Never pull the data itself into context.
3. Bound every command. Never let tests, builds, installs or logs stream into context unbounded.
   • Quiet or failures-only modes: pytest -q -x, vitest run --reporter=dot, go test ./... 2>&1 | grep -v '^ok', cargo test -q, npm ci --silent, make -s.
   • Long jobs: L="${TMPDIR:-/tmp}/out.log"; cmd > "$L" 2>&1; echo "exit=$?"; tail -n 40 "$L". Need more? grep -n -m 20 -E 'error|FAIL|panic' "$L" on the saved log. Never re-run a job just to see more of its output.
   • Iterate on the one failing test, not the whole suite. Run the full suite once at the end, quietly.
4. Never re-read what you have. A file you read or wrote is still in context. Re-read only after compaction or after something else changed it.
5. Batch independent calls. Reads and searches that don't depend on each other go in one turn (parallel tool calls), and shell steps that need no judgment in between go in one command (wc -l a b; grep -n x a | head). Each extra round-trip re-sends everything.
6. Diffs over files. git status -s, git diff --stat then git diff -- <path>, git log --oneline -n 15, git show --stat <sha>.
7. Edit, don't rewrite. Targeted edits only. Never rewrite a whole file to change a few lines, and never paste back into chat code that is already on disk.
8. Narrow searches and fetches. Scope by path and file type, cap results (-m, head_limit, | head -n 30, -l for names only). Pick fields from APIs and JSON (--json a,b, jq '.items[] | {id,name}', per_page). Ask a web fetch a precise question instead of dumping the page.
9. Delegate wide exploration. If an answer means opening 10+ files and you only need the conclusion, hand it to a subagent if your agent has them. Only its summary enters your context.
10. Answer lean. Lead with the result. No step-by-step recap, no restating the diff, no closing summary of what the user can already see, no filler.

Never save tokens by

• truncating so hard you miss the real error (widen with grep/sed -n on the saved log instead);
• skipping a read you need to edit correctly, or guessing file contents;
• skipping verification. Run the tests, quietly.

Limitations

• The savings depend on the workload and the model: in the benchmark a short test-fixing task gained 5%, noisy builds and multi-file features 24-51%; small models such as Haiku 4.5 barely follow the rules without the plugin's read guard.
• The benchmark covers two models and four small tasks on a synthetic repo, and runs vary 2 to 4x.
• The rules cost about 850 tokens of context themselves; on very short sessions they may not pay for themselves.
• The companion transcript audit (tokenleak.py) lives in the source repo and is not included here.

Examples

Locate before reading, and hand the agent only what the next decision needs:

wc -l app/service.py          # size, alongside the search
rg -n "def handle_" app/      # find the region first
sed -n '120,180p' app/service.py

Bound a noisy build and keep the failure visible:

…