Sub-agents & the swarm
How the lead agent delegates to specialized sub-agents that share its sandbox — and why that keeps it fast.
A thread's lead agent doesn't do everything itself. For anything heavy, it spawns sub-agents — focused specialists that do one job and report back. That delegation is what makes the "swarm" inside a single thread.
The specialists
| Sub-agent | Job |
|---|---|
| Explorer | Maps the codebase and answers "where does X live?" so the lead doesn't spend its own context reading files. |
| Coder | Types a slice the lead has already planned. The lead reviews the returned diff with its full context, and sends fixes back to the same coder — it resumes knowing the code it just wrote. |
| Worker | Scoped implementation with an explicit ownership boundary — the files it owns and may edit, and nothing else. |
| Reviewer | Audits the lead's diff against the intent behind it — one lens for correctness and scope, a separate one for exploitability. |
| UI driver | Opens the app in a real browser, drives a flow like a person, and records a video of it working. |
The agent roles reference covers each role's exact capabilities and limits.
Durable memory isn't a sub-agent's job anymore — the knowledge base is maintained by standing automations, so what the swarm learns doesn't depend on any one thread remembering to write it down.
Two ways to delegate
- Blocking — the lead spawns a sub-agent, waits for it, and splices the result back into its own conversation. Used when it needs the answer to continue.
- Detached — the lead launches an agent and moves on. A detached agent can open a pull request; arm auto-merge if you want green CI to land it without you.
They share the thread's sandbox
This is the key difference from threads. Separate threads get separate sandboxes (that's the isolation boundary). Sub-agents inside one thread share the lead's sandbox, so they see the same live working tree — the uncommitted edits, the running dev server, the logged-in browser session. There's no merge step between them.
Why delegation matters
A sub-agent runs with a fresh, focused context — just its task and a short brief about the current state — not the lead's entire conversation. So a deep investigation or a long UI walkthrough costs the lead a short summary, not thousands of tokens of transcript. Pushing heavy work into sub-agents is the main thing that keeps a long-running thread from filling its context window.
Because they share one working tree, fan-out has rules: read-only explorers and reviewers run safely in parallel, but the UI driver runs solo (it controls the one desktop), and you don't run two writers at once. How the lead makes parallel writers safe — and reviews what they return — is the subject of delegation & review.