> ## Documentation Index
> Fetch the complete documentation index at: https://docs.capy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/models-and-pricing#connections) 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](/api-reference/overview) 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:

```text theme={null}
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:

```text theme={null}
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:

```text theme={null}
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.
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.