Skip to main content
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

​
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.

​
In the API

The public API calls a subagent a task: a thread’s subagents are listed at GET /threads/{threadId}/tasks, and each one is read at GET /tasks/{taskId}.

​
Prompts that orchestrate well

Parallel split across disjoint files:
Stacked feature where the pieces overlap:
Cheap parallel audit, shared machine: