mdalexandre/claude-code-lean-agents

Two drop-in subagents that start at about 7.5k tokens instead of the 131k a general-purpose subagent carried on my setup.
Requires Claude Code 2.1.271 or later (2.1.296 or later for the autoCompactWindow line).
---
Why your subagents are expensive
When Claude Code hands work to the built-in **general-purpose** subagent, that agent does not start empty. Before it reads a single word of its brief it loads:
- every CLAUDE.md file the main session loads (user, project and local)
- the list of every skill you have installed
- the definition of every tool from every MCP server you have connected
- the list of every other agent it could start
Then it carries all of that on **every turn**, because each turn of an agent resends its whole context. A post on the Claude developer blog about task costs puts it plainly: "Every turn resends the conversation so far." Cached reads are cheap, but they still count toward your usage.
If you have a rich setup (a long CLAUDE.md, a few dozen skills, a handful of MCP servers), most of that load has nothing to do with the job. A subagent asked to rename a function across three files does not need your Slack MCP, your PDF skill or your notes on deploy policy.
I measured it across my own transcripts. This is the context each agent type carried on its **first** API request, before doing any work:
| Agent type | Runs | Median start | What it loads |
|---|---:|---:|---|
| general-purpose | 852 | 131.1k | CLAUDE.md, skills list, all MCP tools, agent list |
| fork | 10 | 104.6k | the parent conversation |
| Explore (built in) | 20 | 60.2k | skips CLAUDE.md |
| Plan (built in) | 2 | 61.2k | skips CLAUDE.md |
| **lean-worker** | 15 | **7.4k** | its own short rules and 8 tools |
| **lean-checker** | 6 | **7.8k** | its own short rules and 6 tools |
That is **17 to 18 times less** context per turn. And of those 852 general-purpose runs, 654 (77%) never called a single MCP tool, so they paid for a toolbox they never opened.
Your numbers will be different, because the gap depends on how heavy your setup is. The measure_subagents.py script below shows you yours in a few seconds.
What is in the box
| File | What it is |
|---|---|
| agents/lean-worker.md | Worker for bounded jobs: read, edit, run commands and tests, fetch a page |
| agents/lean-checker.md | Blind, read only checker: tests an artifact against criteria, PASS or FAIL per criterion with evidence |
| hooks/lean_dispatch_nudge.py | Optional hook that nudges Claude toward the lean agents when it reaches for general-purpose |
| scripts/measure_subagents.py | Reads your transcripts and prints the starting context of every agent type you use |
| scripts/make_visuals.py | Redraws the diagrams in this README from assets/visuals/spec.json |
| install.sh, uninstall.sh | Copy the agents (and optionally the hook) into place, with backups |
How it works
Nothing clever: it is a handful of frontmatter fields that Claude Code already supports. This excerpt is from agents/lean-worker.md (the full file also has a description and maxTurns: 120):
- **tools** is an allowlist. Without the Skill tool and without any mcp__ tools, the skills list and the MCP tool definitions never enter the agent's context. This is where most of the saving comes from.
- **omitClaudeMd: true** launches the agent without your user, project and local CLAUDE.md files.
- **model: sonnet** and **effort** keep everyday work off the most expensive model. Change them if you like.
- **autoCompactWindow** compacts a long running worker earlier, so a 60 turn job does not drag a huge context through every turn. It appeared in Claude Code 2.1.296; on an older version, delete that line.
- **maxTurns** caps a run (120 turns for the worker, 80 for the checker). An agent that hits the cap stops and returns what it has so far.