Agent roles reference
Every role the lead can spawn — what it does, what it may touch, and what they all share.
Sub-agents & the swarm explains why the lead agent delegates. This page is the reference: each role, what it is allowed to do, and the rules that apply to all of them.
The roles
| Role | What it is |
|---|---|
| Explorer | Read-only research — maps code, traces flows, answers "where" and "how" questions. It has no write tools; its report back to the lead is the deliverable. Never use it to produce files. |
| Coder | Types a slice the lead has already planned. It reports exactly what it changed plus any concerns it hit. |
| Worker | Scoped implementation with an explicit ownership boundary — the files it owns, the contracts it consumes read-only, touch nothing else. A worker can itself fan out further. |
| Code reviewer | Read-only review of the thread's diff against the intent behind it — the plan, your asks, the PR description. It reports; the lead triages and applies fixes. |
| Security reviewer | The same review harness with an exploitability lens — injection, authorization, data exposure — and nothing else. |
| UI driver | Drives Chrome on the sandbox desktop like a person: clicks, types, screenshots, and records video proof. |
| Detached agent | A full independent agent with its own thread and its own sandbox, branched off the default branch. See forks & follow-ups. |
Reading roles and writing roles
The split matters more than the names. Explorers and both reviewers only read, so any number of them can run side by side. Coders and workers write into the shared tree, which is why the lead gives each one a boundary before it starts — that's the subject of delegation & review.
The UI driver is its own case: there is exactly one desktop per sandbox, so exactly one UI driver runs at a time.
Coder and worker aren't the same shape
A coder is the typist for a decision the lead already made. The lead reviews the returned diff with its full context and, when something needs fixing, sends the fix back to the same coder — which resumes with full memory of the code it just wrote, rather than rediscovering it.
A worker owns a slice: an assignment naming its files, the frozen contracts around them, and nothing else. It's the unit the lead uses when a plan genuinely cuts into disjoint pieces.
They work on your live tree
Every sub-agent except a detached agent runs inside the thread's sandbox, on the live working tree. It sees your uncommitted edits and the running dev server, and its own edits are visible to the lead immediately — there is no merge step between an agent and its parent.
Sub-agents never commit. The whole tree commits when the lead's turn ends, so a thread's history stays a sequence of turns rather than a scramble of overlapping writers. See git, diffs & Commit Thread.
What each one starts with
A sub-agent doesn't inherit the lead's conversation. It starts with a fresh, focused context:
task directive
+ brief of current state (diff vs main, recent commits, dev-server port)
+ the project's knowledge manifest
That brief is why a sub-agent doesn't need to re-derive where the work stands, and the manifest is why it doesn't need to re-derive how your codebase is shaped — it opens the Atlas area or entry it needs, on demand. You can see exactly what any agent was given in the context inspector.
Delegation is bounded
A thread can't fork-bomb itself. Fan-out is limited three ways:
- A nesting-depth cap — sub-agents can spawn, but not indefinitely deep.
- A lifetime spawn budget per thread.
- A concurrency cap — spawns beyond it queue and start automatically as slots free, so a wide fan-out drains on its own instead of failing.