Subagents & multi-agent¶
For work that's too big or too parallel for a single conversation, gdc can delegate. The agent can hand a focused piece of work to a subagent, and — for larger efforts — coordinate several of them at once.
Subagents¶
A subagent is a fresh, focused agent that the main agent spins up to handle one self-contained job: "investigate why this test fails", "summarise these three modules", "draft the migration for this file". The subagent works on its own, then returns its result to the main conversation.
You don't launch subagents yourself — the agent decides when a task is worth delegating. Because spawning one is a meaningful action, gdc asks for your approval before it does (in interactive use).
Why delegation helps¶
- Focus. A subagent starts clean, without the main conversation's clutter, so it can concentrate on one thing.
- Parallelism. Several subagents can work at once on independent pieces.
- Auditability. Each subagent gets its own recorded session, linked to the parent, so you can see exactly what each one did.
Following along¶
In the terminal app:
- Ctrl+W opens the subagent picker and lets you drill into a running subagent to watch its work.
- Ctrl+J lists active subagents alongside background commands.
To see the structure afterwards:
Coordinated multi-agent work¶
Experimental
Coordinated multi-agent work is an advanced, evolving capability. The building blocks are in place, but the behavior may change. Use it for experimentation; prefer single-agent or simple subagent delegation for day-to-day work.
For a bigger task that naturally splits into parallel parts — auditing many files, a broad migration, gathering evidence from several angles — the coordinator profile lets one agent manage a group of subagents: handing out pieces, collecting results, and combining them.
gdc print --profile coordinator \
"audit every module for missing input validation and summarise findings"
You can tune how many subagents run at once and how their work is
budgeted through the [task] configuration:
For the durability options that matter when running coordinated work on a server (resuming interrupted subagents, archiving finished ones), see the Admin guide.
When to use what¶
| Situation | Approach |
|---|---|
| A single, contained task | Let the agent work directly. |
| One focused side-investigation | The agent delegates to a subagent. |
| Many independent pieces at once | The coordinator profile (experimental). |