Subagents
A subagent is a full child agent your thread's agent spawns to work in parallel: its own conversation, its own tools, and usually its own machine. A subagent can run commands, open PRs, and spawn subagents of its own, up to three levels deep. Subagents are addressed by position: the first is Subagent 1, and Subagent 1's third subagent is Subagent 1.3.
You don't create subagents directly; you ask the agent to split the work, and it drafts, starts, and coordinates them. A subagent starts as an editable draft (a title plus the full prompt its agent will run with) and does nothing until started, so the agent can lay out a whole plan, refine it, and launch pieces in the right order.


Subagents work in isolation
A subagent starts from its prompt alone. It hasn't seen your thread's history, your earlier corrections, or the files the parent explored: everything it needs must be in the prompt it's given. And the parent isn't fed each step as it happens: it gets the final summary automatically and reads interim progress only when it asks. Subagents are cheap parallelism precisely because they don't drag the whole conversation context with them.
Shared vs fresh machines
A subagent either shares the parent's machine or gets a fresh one, and the split follows writes:
- Shared: the subagent works on the parent's machine and sees its working tree exactly as it stands, uncommitted changes included. Right for subagents that only read: exploring, auditing, summarizing.
- Fresh: the subagent boots its own machine with a clean checkout from the upstream branch. Right for subagents that write: each writer gets an isolated tree, so two subagents editing code can't collide with each other or with the parent.
Capy must choose one explicitly whenever it starts a subagent. The start result names the placement and machine id, so a mismatch is visible before the child reports missing files.
Parallel vs stacked
- Parallel subagents run simultaneously and must touch disjoint parts of the codebase: different packages, different files. Each ships its own PR.
- Stacked subagents depend on each other or touch overlapping files: Subagent 1 runs and ships its PR, then Subagent 2 starts from Subagent 1's PR branch and builds on top. Slower, but conflict-free where parallel would collide.
When in doubt, stack. A merge conflict between two parallel subagents costs more than the waiting.
Subagent lifecycle
| Status | Meaning |
|---|---|
draft | Created but not started; the prompt is still editable. |
working / waiting | Running, or parked on an external event like CI. |
idle | At rest, including after a stop. A stopped subagent is just an idle subagent. |
done | Delivered a final result to the parent. |
failed | Ended in an unrecoverable error. |
How results come back
A subagent reports to its parent through explicit messages:
- A subagent that finishes delivers its final summary to the parent, which wakes and acts on it.
- A subagent that gets blocked (it needs a decision, access, or credentials) surfaces its actual question to the parent as a notification. The parent can answer it, answer with your help, or escalate to you.
- Interim progress messages don't wake the parent; it reads them on demand when it checks on the subagent.
Reviewing and shipping subagent work
A completed subagent's work sits on its machine until someone ships it. The parent reviews by inspecting the diff on the subagent's machine, then either opens a PR from the subagent's branch, patches small problems itself, or sends the subagent targeted feedback and lets it revise. You can direct any of this: "check Subagent 2's diff before opening the PR" or "tell Subagent 1 the API changed and have it rebase."
Models per subagent
Each subagent can run on its own model: a cheaper model for mechanical work, a stronger one for a gnarly refactor, or a connected subscription like Codex. By default subagents inherit the thread's model; ask for a specific split when you want one: "run the test-writing subagents on the cheapest reasonable model."
Coordinating across threads
Subagents stay inside one thread. For genuinely separate workstreams, the agent can also create sibling threads (each a root-level workspace with its own agent, machines, subagents, and PRs) and message them. A sibling thread answers to you in its own thread, and a coordinating agent has to explicitly read a thread's state to learn anything. Use sibling threads only when you're deliberately running one controlling thread over several long-lived workstreams; ordinary parallel work belongs in subagents.
For a long-lived agent that directs threads for you, use a Captain. To compare side chats, forks, subagents, and Captains, or to have one thread read another, see How threads keep working.
In the API
The public API lists a thread's subagents at GET /threads/{threadId}/subagents and reads each one at GET /subagents/{subagentId}. The original /threads/{threadId}/tasks and /tasks/{taskId} routes still answer with the same data.
Prompts that orchestrate well
Parallel split across disjoint files:
Migrate our API handlers from Express to Fastify. Split it into parallel subagents by directory (one subagent each for routes/auth, routes/billing, and routes/webhooks) on fresh machines, each shipping its own PR. Give every subagent the migrated example in routes/health as the pattern to follow, and require passing tests before it reports done.Stacked feature where the pieces overlap:
Add org-level audit logging. Stack it: Subagent 1 builds the audit_log table, migration, and write API, and ships a PR. When that PR is up, start Subagent 2 from Subagent 1's branch to wire logging into the settings and members endpoints, as a second PR on top. Review Subagent 1's diff before starting Subagent 2.Cheap parallel audit, shared machine:
Before we cut the release: spawn three read-only subagents on your machine to audit the diff since v2.3: one for breaking API changes, one for missing migrations, one for untested code paths. Have each report findings with file references, then give me the combined list ranked by risk.