Subagents Turn The CLI Into A Small Scheduler
A subagent is a scoped runtime. It carries its own tools, its own permission, its own transcript, and often its own workspace. It can run in the background while you work. The scope you set before dispatch decides whether it helps.
Every subagent costs a full runtime. Spawn one only when the work is a job.
Delegation model
When one job is too big, the lead hires subagents. Each one gets its own room, its own tools, and its own copy of the instructions. It works without bothering the others.
What comes back is one short answer. The mess stays in the room where it was made, and the lead never has to walk through it.
Many rooms working at once, one tidy summary returning. That is how one tool becomes a team.
I used to read a subagent as one more prompt in a role. Spawning one assembles a runtime and hands it a slot for the answer. The figure runs three subagents under one lead. Flip the delegation from crisp to vague and watch what comes back.
01Spawning a worker is a job request
The prompt is the smallest part of a spawn order. The rest names the agent type, the model, the background flag, the job name, the team, and the directory. It also says whether the subagent gets a workspace of its own. Those fields decide how the job runs.
Checks run before anything spawns. The order asks which agent types are allowed here, what outside connections they need, and what permission they carry. Then the background flag splits the path. A background job returns control at once, and the turn stays yours. A foreground job spends the turn for you.
02The setup builds the worker's whole world
The room gets built before the subagent does one thing. The setup opens the outside connections and writes a fresh copy of the system prompt. It sets a permission mode, usually narrower than yours. It adds the record of files read, the tool list, the hooks, and any extra know-how the job needs. The order of that matters. All of it is fixed before the subagent starts the same loop from the first idea of this guide.
The briefing that programs an agent and the permission that gates it both came earlier in this guide. A subagent gets its own copy of each, assembled for one job before it starts. The narrow version is also the cheap one. A read-only subagent never receives the project notes or the git status it will not read. Across millions of subagents, that saving is real.
03Running in the background forces the discipline early
A detached subagent cannot stop and ask you. Every permission it needs has to be settled at dispatch. It hits a closed door, writes the refusal down, and carries on to the next step. Its short tool list keeps everything else out of reach.
The rule
Name what the subagent is allowed to do before it starts, or keep the job in the foreground. A rule it carries from the start is a rule it never invents halfway through.
04Transcripts make background work inspectable
Every subagent keeps a transcript, and every job keeps an address. The entry carries a name, a readable result, a status, and a bell that rings at the end. The address is how you find the job after it leaves the chat.
One tidy result goes back to the lead. The transcript stays at its address with the request, what the subagent did, and the place to look.
05An isolated workspace moves conflict to a clean line
A subagent can run in its own copy of the project, and git works inside that copy. The mess starts when two subagents edit the same file. Cleanup follows one rule: a workspace is discarded only when the subagent changed nothing in it. A workspace built by an outside hook is always kept, because the system cannot tell what that hook owns. The merge work stays, and it moves to one clean line you handle once. For code, that trade is worth taking.
06Teams and messages add coordination
The team tools push the shape further. You can stand up a team with one lead and its own to-do list. It runs like a small project. A subagent can message one teammate or broadcast to all of them. It can hand a plan back for approval, or reach across to another session.
The largest version is one lead over many subagents. It splits the work, spawns them at once, and keeps their writes in order. Then it checks what returns and ties the pieces into one answer.
Two rules carry the arrangement. A subagent cannot see your chat, so every job has to stand on its own. The lead must synthesize what comes back rather than forward it. Done means verified holds for delegated work, and the lead owns that check.
07When subagents help, and when they do not
Subagents earn their cost when the scope is crisp. Examine one module and report what it does, or verify a change in a copy of the project. Search a large codebase for one behavior. Run something long and leave the result at a known address. They waste it on vague orders: look around and help, fix whatever is wrong, do the same elsewhere. Crisp scopes come back as pieces the lead can join. Overlapping scopes come back as the same ground twice. The split is one property: the job stands alone, with its own tools, permission, and a checkable result.
The cost
Subagents spend tokens, split the transcript, and repeat each other when their scopes overlap. A loose scope lets one wander outside its job. The lead can also accept a result it never checked. The system covers part of this with few tools, isolated workspaces, and records that stay put. It also caps how many run at once, usually a handful and rarely more than a couple of dozen. Drawing the scope stays with the lead, and with you.
Decision
Write the subagent prompt so it reads with this chat closed. Name the check it has to pass, and name it before you dispatch.
A job that fails either test is a wish. The next idea picks the smallest thing that carries a new job: tool, skill, command, subagent, or hook.