{"slug": "a-set-of-rules-to-save-tokens", "title": "A set of rules to save tokens", "summary": "A GitHub repository published by cicerohellmann, token-savings, grades local Claude Code transcripts to quantify how much spend a set of token-saving rules would have avoided, reporting that reading and writing context accounted for about 74% of the author's bill while visible prose was about 1%. On the author's data, a rule of one fresh helper per task cut that waste from 2.5% to under 0.1% of spend, lean helper types cut startup waste from 9.3% to 1.5%, and model-by-task routing cut model waste from 4.3% to 1.6%, while hot wakes rose from 1.1% to 4.1% and context rewrites fell from 6.9% to 4.1% with no tested cure yet. The repo's grade.py measures each check red to green, and Claude Code turns the grade into advice plus installable rules in adopt/CLAUDE-rules.md, with the comparison covering 5–9 Oct 2026 before the rules and 9–16 Nov 2026 after them.", "body_md": "Find the Claude Code tokens that bought nothing, and stop spending them.\n\nThis repo does three things:\n\n1. **Measures.**`grade.py` reads your local Claude Code transcripts and works out, check by check,\nhow much of your spend a known rule would have saved. Each check gets a grade, red to green, and\nso does the total.\n2. **Explains.** Open Claude Code here and it turns the grade into plain advice: what each red check\nfound, why it costs, which of your chats caused it, and what to change.\n3. **Fixes.** It hands you the rules and lean helper types that cure each check, ready to install,\nand you re-grade a week later to see if the grade moved.\n\nThe grade is about waste, not volume. Spending more while getting more done is fine; the question is how much of what you spent bought nothing.\n\n**Words used here.** *Helper*: a Claude Code subagent, started with the `Agent` tool. *Main chat* (the\n\"lead\" in the evidence files): the chat you type in, which starts helpers. *Loop*: an agent that\nrepeats work on its own, often through helpers. *Watcher*: a loop, `/loop` or `Monitor` that keeps\nchecking something. *Wake*: one such check, which re-reads the whole chat.\n\n**Which rules apply to me.** One chat and no helpers: only \"read big output in pieces\", \"batch\ncommands\" and \"compact at a pause\"; the rest does nothing for you. You use helpers: add one task per\nhelper, lean types, model by task and unnamed helpers (all in [adopt/CLAUDE-rules.md](https://github.com/cicerohellmann/token-savings/blob/main/adopt/CLAUDE-rules.md)).\nYou run loops, `/loop`, `ScheduleWakeup` or `Monitor`: also the watcher rules, which are marked in that file.\n\nEvery step an agent takes re-sends its whole conversation. So the cost of a step is roughly its\n**context size × model price**, and the cost of a task is that **× the number of steps**. Almost\nevery saving here comes from one of three levers: a smaller context, fewer steps, or a cheaper\nmodel. The text the agent writes to you barely matters: on the author's data, visible prose was\nabout 1% of the bill, while reading and writing context was about 74% (see [Results](#results)).\n\nEach strategy is one check in the grader, except those marked \"not graded\". \"Effect\" is what\nhappened on the author's data after the rule was adopted: the share of spend each check found\navoidable on 5–9 Oct 2026, before the rules, and on 9–16 Nov 2026, after them\n([GRADES.md](https://github.com/cicerohellmann/token-savings/blob/main/GRADES.md) has the mechanism, thresholds and confidence for each, with the original October counts).\n\n| strategy | the waste it stops | check | effect so far | \n|---|---|---|---|\n| **One task per helper.** A fresh helper with a full brief for each new task. | A helper given task 30 re-reads tasks 1–29 on every step. | re-task | 2.5% → under 0.1% of spend | \n| **Lean helper types.** Helpers that load only the tools their job needs. | Every step of every helper re-reads 40–50k of tool schemas and instructions it never uses. | startup | 9.3% → 1.5% | \n| **Model by task.** haiku for lookups, sonnet for routine work, opus for judgment ([MODELS.md](https://github.com/cicerohellmann/token-savings/blob/main/MODELS.md) ). | Opus at 40× the price of Haiku doing a grep. | model | 4.3% → 1.6% | \n| **Small, rare watchers.** Heartbeats 30+ min apart, a filter that only wakes on real news, never watch from a big chat. | A 150k chat re-reading itself to say \"nothing changed\". | hot wakes | grew: 1.1% → 4.1% | \n| **Wake inside the cache's life, or small.** Don't let a big chat sit idle past 5 minutes and then wake. | After the cache expires, the whole context is written again at 12.5–40× the read price. | rewrites | 6.9% → 4.1%, no tested cure yet | \n| **Read big output in pieces.**`tail` ,`grep` , small screenshots. | A 50k log stays in context and is re-read on every later step. | big outputs | 0.1% → 0.2% (rule was already in place) | \n| **Compact at a pause; the lead stays small.** The lead coordinates from short reports and keeps state in a file. | A chat working at 150k+ pays for all of it on every step. | bloat | 0.1% → under 0.1% (already in place) | \n| **Open helpers without a name.** An unnamed helper ends itself when it reports. | A named helper stays open in the chat until shut down, and its name invites re-tasking it. | not graded | named: 99% of one lead's helpers before; 1 ask in about 180 helpers after a hook began stripping names | \n\nTwo more rules in [ETIQUETTE.md](https://github.com/cicerohellmann/token-savings/blob/main/ETIQUETTE.md) aren't graded yet: **batch commands** (one call\nwith five greps instead of five calls) and **don't run more helpers than a shared lock can serve**\n(helpers queued on one build or device sit on their context while the cache expires).\n\nOn the author's data the overall avoidable share went from 23.3% (red) to 11.3% (yellow). The two checks that hold most of what's left, hot wakes and cache rewrites, have no measured cure yet.\n\nOn the author's machine, every Claude Code call from 5 Oct to 16 Nov 2026, priced at today's API list prices for every model.\n\n**Each step got about 17% cheaper.** The average day cost $0.053 per step before the rules\n(5–16 Oct, 8 full days) and $0.044 after (17 Oct – 16 Nov, 29 full days), leaving out Fable\n(see limits). A permutation test on the daily figures puts the chance of this being luck below 0.1%.\n\n**Because context got smaller.** Each step re-sent about 107k tokens of context before and about\n81k after. Output per step did not fall in the same way (about 760 tokens per step early October,\n560 late October, 760 again mid November).\n\n**Where the money goes** (17 Oct – 16 Nov):\n\n| part of the bill | share of $ | \n|---|---|\n| reading and writing context (cache reads and writes) | 74% | \n| output tokens | 26% | \n| … of which visible prose, the only part terse \"caveman\" prompting cuts | about 1% | \n| … the rest: thinking and tool calls (mostly shell commands) | about 25% | \n\nProse also stays in context and is re-read on later steps, so 1% is a floor, but even a few times\nthat is small next to context. Making context smaller cut cost per step by 17%; cutting prose in\nhalf would cut it by about half a percent. To see this split for your own chats, run\n`python3 grade.py --split` (same window options as the grade).\n\nThe grade above prices each model at its own list price at the time (October's Opus 4.8 at the older, higher rates). The 17% and the context figures price every model at today's rates, so the change in price doesn't count as a saving. Don't compare the two sets of dollars directly.\n\nYou need Claude Code and Python 3.9+.\n\n```\ngit clone https://github.com/cicerohellmann/token-savings\ncd token-savings\nclaude\n```\n\nThen say one of:\n\n- **\"Evaluate my token spend.\"** It runs`grade.py` on your last 7 days, shows the grade table, and\nexplains every non-green check with its cure. Name a window (\"the last 14 days\") or your repos\n(to also see work per dollar) if you like.\n- **\"Give me your improvements.\"** It asks whether you want the whole machine or one project, then offers to add[adopt/CLAUDE-rules.md](https://github.com/cicerohellmann/token-savings/blob/main/adopt/CLAUDE-rules.md) to your`CLAUDE.md` and copy the`worker` ,`reviewer` and`scout` helper types in[adopt/agents/](https://github.com/cicerohellmann/token-savings/blob/main/adopt/agents) to your`agents/` folder, and to install the helper gate hook from[adopt/hooks/](https://github.com/cicerohellmann/token-savings/blob/main/adopt/hooks) . It does this with`adopt/install.py` : a dry run shows each change, and it applies them only when you say yes. \"Undo the token-savings changes\" removes it again.\n\nOr run the grader yourself: `python3 grade.py` (`--days N`, `--since/--until \"YYYY-MM-DD HH:MM\"`,\n`--repo PATH:BRANCH`, `--json`, `--split`). It reads `~/.claude/projects` (or `$CLAUDE_CONFIG_DIR/projects` if you set that) and nothing else, and sends nothing\nanywhere. Claude Code deletes transcripts after 30 days by default, so that is as far back as it\ncan grade.\n\n| file | what it is | \n|---|---|\n| [GRADES.md](https://github.com/cicerohellmann/token-savings/blob/main/GRADES.md) | the grade scale and every check: mechanism, what is counted, thresholds, confidence, cure | \n| [ETIQUETTE.md](https://github.com/cicerohellmann/token-savings/blob/main/ETIQUETTE.md) | the rules for running helpers (subagents), with the evidence for each | \n| [MODELS.md](https://github.com/cicerohellmann/token-savings/blob/main/MODELS.md) | which model and effort for which kind of helper task | \n| [CASE.md](https://github.com/cicerohellmann/token-savings/blob/main/CASE.md) | the afternoon that started it: three agent loops and where their tokens went | \n| [FRAMEWORK.md](https://github.com/cicerohellmann/token-savings/blob/main/FRAMEWORK.md) | how every lesson here is written up: situation → mechanism → proposal → prediction → measurement → result → confounders → status | \n| [adopt/](https://github.com/cicerohellmann/token-savings/blob/main/adopt) | the rules block, the lean helper types, the helper gate hook, and `install.py` that installs and undoes them | \n| `grade.py` | the grader (standard library only) | \n| [CLAUDE.md](https://github.com/cicerohellmann/token-savings/blob/main/CLAUDE.md) | what Claude does when you open it here | \n\n- The evidence comes from one person's machine, running many multi-agent loops, in October and November 2026. The grade thresholds are calibrated on that data only.\n- Each check is an upper bound: some carried context or late wakes were really needed.\n- Other changes landed in the same weeks, so the effects above can't all be credited to one rule.\n- Shares are of spend priced at API list rates. On a subscription they show where your limit goes, not a bill.\n- The 17% leaves out Claude Fable 5.2, which the author started using in November at twice Opus's price; with it included, cost per step for 9–16 Nov was back to about where it started. It also says nothing about work done per step: that wasn't measured.\n- Versions of `grade.py` before 17 Nov 2026 used old prices, under-counted output and misread when\na chat was idle. The strategy table, the overall share and the`--split` figures come from the\nfixed version. The 17% and the context figures come from the author's separate analysis scripts,\nwhich are not in this repo.\n- The grade says nothing about whether the work was worth doing.", "url": "https://wpnews.pro/news/a-set-of-rules-to-save-tokens", "canonical_source": "https://github.com/cicerohellmann/token-savings", "published_at": "2026-11-17 21:23:12+00:00", "updated_at": "2026-11-17 21:43:58.485540+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools"], "entities": ["Claude Code", "cicerohellmann", "token-savings", "grade.py", "Anthropic"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/a-set-of-rules-to-save-tokens", "markdown": "https://wpnews.pro/news/a-set-of-rules-to-save-tokens.md", "text": "https://wpnews.pro/news/a-set-of-rules-to-save-tokens.txt", "jsonld": "https://wpnews.pro/news/a-set-of-rules-to-save-tokens.jsonld"}}