khosra/ideas/token-conservation.md

Token conservation

Status: parked Raised: 2026-07-28

Why it came up

Development pace is limited by session and usage limits, not by typing speed. Cutting token cost per feature buys more features per session. The goal is explicitly conserve tokens without lowering output quality — not "be terse and worse".

What is already established

Do not re-derive these.

• Turn count dominates, not file size. The whole context is re-sent on every tool call, so a six-call verification sequence costs roughly 6× the context. Batching is the biggest lever.
• CLAUDE.md is the most expensive file per byte in the repo — it is re-sent every turn.
• Agent prose is a large, entirely self-inflicted cost. The target is density, not brevity: same information, fewer words. Length follows content; padding, restatement, hedging and rhetorical closers do not.
• Two accepted rules cost tokens on purpose and are worth keeping: hard rule 8 (docs ship with the change) and the topic-ownership read floor. The ownership table is what keeps the floor cheap — it sends you to one doc instead of a grep sweep.

The six mechanisms, ranked by saving

1. Batch tool calls — one Bash call per phase, not per command.
2. Prose density in reports and replies — cut restatement and flourish, keep every finding, number and caveat. Biggest win, costs nothing. Not a length cap: truncating information is not a saving.
3. Line ceiling on CLAUDE.md in budgets.env, gated like any other budget.
4. Targeted reads — grep -n plus Read offset/limit; whole-file reads only for the doc that owns a rule being asserted.
5. Evidence proportional to risk — one case for a behaviour change, a full matrix only for a gate or a security boundary.
6. Never re-read after Edit; run verify.sh once per feature, at the end.

Open question — needs the human

Subagents for fan-out search. Dispatching "find every place X appears" to a subagent keeps its file dumps out of the main context: you pay for the conclusion, not the search. A real multiplier on exploration-heavy work. Currently disallowed unless explicitly requested, so it is a policy call, not a judgment call.

Cheapest next step

Apply 1–6 as one batched change: CLAUDE.md (efficiency rule), SKILL.md (report cap, evidence proportionality), budgets.env + verify.sh (CLAUDE.md line ceiling). Trips the HARNESS.md coupling gate by design. Estimated one feature-sized change.