# Tokenleak

> Token-lean rules for coding agents: cut the context re-sent on every later call (big reads, noisy logs, re-reads, serial calls) without losing correctness.

- Skill: `iradoweck/tokenleak` (Agent Skill)
- Install (CLI): `npx get-skill add iradoweck/tokenleak`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iradoweck/tokenleak/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: iradoweck (https://skillmd.com/u/iradoweck)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/iradoweck/tokenleak

---


# 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="$(mktemp)" || exit 1; 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:

```bash
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:

```bash
L="$(mktemp)" || exit 1; npm test > "$L" 2>&1; echo "exit=$?"; tail -n 40 "$L"
grep -n -m 20 -E 'error|FAIL' "$L"
```

Count instead of pasting data into context:

```bash
python3 -c "import json;print(len(json.load(open('events.json'))))"
```

