token-budget

Token & Context Discipline

Trigger phrases: "token budget", "token cost", "context window", "context management", "context is full", "clear context", "running out of context"

A subagent exists for context management: it runs in its own window and returns only its summary to the main thread — intermediate noise (file reads, searches, logs) never enters the main context.

Warning — measured, not guessed. Each subagent re-pays its full context from scratch: in a real transcript the first turn was cache_read=0, every token cache_creation — nothing is shared with the main thread's cache. A no-op subagent (task = "reply DONE") already cost ~10k tokens with restricted tools and ~16k with full tool access; that floor is base system prompt + tool schemas, paid fresh every time. Of the always-on material only the skill listing (~2.5–3k tokens) is inherited by a subagent — the discipline (DISCIPLINE.md/CLAUDE.md) and the agent descriptions are not injected into it. So a delegation is worth it for isolation / parallelism / a clean window, or when the isolated work would otherwise cost the main thread more than that ~10–16k floor — never by default.

Rules

1. Output = summary. The agent returns a short, structured summary to the main thread; it does not return raw logs / file dumps / long code.
2. Move to a file. Heavy output (a plan, scan report, inventory) is written to docs/*.md; a summary + pointer comes back. (local, in gitignore)
3. Delegation threshold. Noisy/heavy work (reading many files, scanning, research) → subagent. A single tool-call / small work → main thread. Concretely: if the isolated work won't save the main thread more than the ~10–16k fresh-context floor a subagent costs, keep it on the main thread — delegate for isolation, not to shave a few reads.
4. Least tooling. An agent holds only the tools it needs; extras accidentally pollute the context + burn the limit.
5. Lean SKILL.md. Skills load into the main context; heavy reference goes to a separate file, only when needed.
6. Targeted reading. Instead of reading a whole file, pinpoint with Grep/Glob.
7. Manage with /context. session-manager-csk recommends continue/handoff+clear based on the real percentage; at a phase boundary, /clear.
8. Bound what a command hands back. All of the rules above govern the context's own footprint; none of them govern what a single Bash call dumps into it. A find over a monorepo, an unfiltered log, a full test run — each returns everything to the main thread whether or not any of it is read. Ask for the answer, not the corpus: grep -c over grep, | tail -20 over the whole file, --quiet/--porcelain where the tool has one, and a redirect to a file plus a pointer when the output is genuinely needed later (rule 2).
9. Cut what nothing reaches — with evidence, not a hunch. Every installed skill spends its name and description in EVERY session, forever. bash .claude/eval/utilization.sh reports which skills actually fired in this project's transcripts and how many bytes the cold ones cost, which is the list doctor.sh §4a's skillOverrides: name-only advice needs and never had. Read it as evidence, not a verdict: a skill that only fires during an incident is doing its job by existing. --all-projects widens the scope; by default it reads this project only and prints names and counts, never paths or content.