EP3 Subagents: hand work to helpers with a room of their own
A subagent is a helper the main AI hands work to. It works in its own room and returns only the result. When to use one, and how to limit it.
- A subagent works in its own context and returns only a summary, so the main head stays clean
- A specialist should get only the access it needs, and carry that job's lessons in its agent file
- A subagent cannot see the main conversation, so brief it fully, like someone who just walked in
In EP2 we gave the AI knowledge, procedures and enforced rules, but it still does everything in one head. Big jobs then hit two problems: the head fills up from reading so many files, and only one thing happens at a time. This episode fixes both with subagents.
The problem: one head is not enough
The AI has a working memory while it works, called the context. Every file it reads and every command output it sees takes space there. A job like “find everywhere this function is called across 200 files” reads a lot, yet what you actually need is a few lines of answer. If the main head reads it all, its space fills with things it will never use again.
In a company, the manager does not dig through every folder personally. They send an assistant to look and take back a summary.
Principle: work that reads a lot but answers briefly, or work that can be split off, goes to a helper in their own room, who sends back only the result.
How a subagent works
- The main AI writes a brief for the subagent
- The subagent starts in a fresh, empty context, reads files, runs commands, and finishes the job
- It sends back only a summary; the files it read do not come back with it
- Independent jobs can go to several subagents at once
Claude Code comes with some built-in subagents, such as a read-only code explorer, and you can create your own specialists.
Creating a specialist
They live at .claude/agents/<name>.md. It looks like a skill, but it is a “person”, not a “procedure”:
---
name: reviewer
description: Review code that was just changed for bugs and security holes. Use after editing code, before committing.
tools: Read, Grep, Glob, Bash
---
You are a code reviewer. Read the latest diff and find bugs that produce wrong results.
Do not edit files. Report a list: file:line, problem, fix.The tools line matters a lot. This one has no file-editing tools, so it can only review, never change anything itself. Each helper should get only the access its job needs, like a new hire who does not get a key to every room.
A real example: a helper that carries its lessons
The 3D design site we run has a specialist called forge-smith with one job: building and fixing the generators for 3D models. Its agent file carries two expensive lessons.
- The first came from a real bug that broke the live site. A library was installed on the development machine but not on the server, so code passed every local test and then failed on the live site for every user. The agent file now says plainly which functions must never be used in code that runs on the server.
- The second is the boundary of its job. It does not deploy and does not commit. When it finishes, it sends a render and its numbers to the main agent, which decides whether anything goes live.
Lessons like these, buried in a project-wide CLAUDE.md, get lost among everything else. In the file of the helper that does that exact job, they are seen every time it is called.
Working in parallel: a desk each
Send several jobs that all edit code at once and they overwrite each other’s files. The fix is to give each its own git worktree, a second copy of the project on its own branch, and merge when done.
That same 3D project once ran subagents in parallel until 8 worktrees were left lying around. The work really did go faster, and it taught us that someone has to clean up finished worktrees too.
Downsides to know
- It cannot see the main conversation. The brief must stand alone: what to do, which files, what done means, and what to send back.
- Total tokens can go up, because each one starts from zero and reads files itself. You gain speed and a clean main head, not correctness for free.
- Summaries can drop things. What the subagent does not write back, the main agent never learns. For important work, ask it to report what it did not check as well.
Try it in 10 minutes
- Create
.claude/agents/reviewer.mdfrom the example above - Change some code, then say “have reviewer review what I just changed”
- Notice the main agent gets back only a list of issues, not every file the reviewer read
Where a person is needed
A person designs the org chart: what each helper does, how much access it has, and who makes the final call. For example, a helper may build things, but going live has to pass through the main agent and a person. A good chart prevents more damage than a smarter model does.
Next episode
With several helpers in place, the next question is how to chain the work into a production line, so every job goes through the same steps, passes checkpoints and skips nothing. EP4 covers workflows.
FAQ
Do subagents save money?
Not always. Each one starts from zero and reads files itself, so total tokens can go up. What you get is a clean main context and parallel work. Running subagents on a cheaper model does save money, which EP5 covers.
Can several subagents edit the same files at once?
They should not; they will collide. When several need to change code at the same time, give each its own git worktree and merge the work afterwards.
Commands and settings were tested on sample systems. Try them on a test machine before production.