Claude CodeLesson
Subagents
One session can hand parts of its work to other agents and keep only their answers. Those agents start knowing nothing, so everything they need has to be in the message that starts them.
Know subagents already? Skip to In Terrarium.
Outside the box · General
The concept
A subagent is a helper Claude starts inside a session. It runs in its own context window, with its own system prompt and tools. It doesn't see the conversation that started it, the Skills already run or the files already read: it gets a message describing the task and works from that. When it finishes, only its final report comes back, so the searching and reading it did stays out of the main conversation.
A subagent that edits files needs a checkout of its own, or parallel helpers overwrite each other's work. Claude Code can give each one a fresh git worktree: ask Claude to "use worktrees for your agents", or add isolation: worktree to a custom subagent's frontmatter.
---
name: refactorer
description: Applies one mechanical refactor across many files
isolation: worktree
---
Apply the refactor across every affected file, run the tests,
and report the results.
Full referenceClaude Code docs: Create custom subagents
In Terrarium
Terrarium dispatches subagents for reviews, research, screenshots and whole branches of work. How to dispatch them is one , .agents/skills/dispatch-subagents/SKILL.md, which CLAUDE.md says to read before writing a subagent brief or resuming a stopped subagent. A guard, scripts/hooks/dispatch-read-guard.ts, denies the main session's first dispatch until it has read the Skill. Its goal is that every subagent's work lands, is right, and is never stranded: finished but uncommitted, or never seen by the session that asked for it.
Most of the Skill is a checklist for the brief. Its two main ideas, in its own words:
29The subagent sees none of your context, so the brief is self-contained. Include
30every line that applies.
⋯<!-- … -->
48- Commit before stopping, even mid-gate: an agent can end at any time. Push
49 once its branch is reviewed ("Scope and trust").
The brief:
- sets up the agent's checkout: the commit to start from and the install (Git worktrees has the details);
- says to commit before stopping, even halfway through a check;
- gives every file the agent writes, scripts included, a name of its own in a folder made for it.
The Skill also says who reviews. A subagent building a branch hands it back committed and unpushed. The session that dispatched it reviews the branch and sends every fix back to the same agent, which pushes once a review comes back clean. The dispatching session then opens and lands the PR itself.
Some things a subagent may not do. It can't dispatch subagents of its own, so a review or a nested dispatch is the dispatching session's job. It writes no session log (Git worktrees says how the log script refuses). And a guard denies it any background shell command.
A stopped subagent is resumed with SendMessage to its agent id, never dispatched again. A new dispatch gets a new checkout and no memory, so it can start a second copy of a branch or leave the first one's commits behind.
Why it's built this way
- One checklist, read each time. A subagent's mistakes are often silent: agents shared one check log, each reading another's overwrite, and the dispatching session published a wrong diagnosis. So the brief's rules, down to git run as
git -C <root>and the shared scratch folder, sit in one Skill read before each brief. The cost: a long brief for a small task. .agents/skills/dispatch-subagents/SKILL.md. - No background commands. A subagent's turn ends when it stops to wait, and nothing wakes it when a background command ends, even when the brief said how to check. So a guard refuses the command outright. The cost: a long check runs in the foreground, and one outlasting a single call needs a resume. scripts/hooks/subagent-background-guard.ts.
- Review by the dispatcher. A branch beyond a simple change is reviewed before its first push, since pushing leads straight to a PR. A subagent can't start a reviewer, so the dispatching session reviews while the subagent waits unpushed. Fixes go back to the same agent, which still holds the worktree. The cost: a round trip per review. .agents/skills/dispatch-subagents/SKILL.md.
What to watch for
- The brief is all it knows. A rule, a count or a source the dispatching session already holds has to be in the brief, or the subagent derives it again or misses it.
- Its report is a claim. A subagent's prose is checked against the source it cites before anything ships on it.
Try it in your project
Next time you hand Claude a task with parallel parts, write the brief as if to a stranger: the commit to start from, the setup command, what to commit, and what to report back. Compare its report with the files it names before you act on it.
Where next
- LessonGit worktrees
- LessonCLAUDE.md
- LessonClaude Code Skills
- LessonBlocking hooks
- JournalHow Humans & Agents Work
Walkthroughs through this Lesson
- WalkthroughAsking an agent for a change
Last updated · Latest source on GitHub ↗