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

# Tasks

> How the agent parallelizes work with task subagents: shared vs fresh machines, parallel vs stacked, and how results come back.

A task 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 task can run commands, open PRs, and spawn tasks of its own, up to three levels deep. Tasks are addressed by position: the first is Task 1, and Task 1's third task is Task 1.3.

You don't create tasks directly; you ask the agent to split the work, and it drafts, starts, and coordinates them. A task 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.

## Tasks work in isolation

**A task 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. Both cut the same way: tasks are cheap parallelism precisely because they don't drag the whole conversation with them, and bad task prompts are the number one way orchestration goes wrong. If a task came back with the wrong thing, the fix is usually a more specific prompt, and you can say so: "give the task the exact file list and the pattern to follow."

## Shared vs fresh machines

A task either shares the parent's machine or gets a fresh one, and the split follows writes:

* **Shared**: the task works on the parent's machine and sees its working tree exactly as it stands, uncommitted changes included. Right for tasks that only read: exploring, auditing, summarizing.
* **Fresh**: the task boots its own machine with a clean checkout from the upstream branch. Right for tasks that write: each writer gets an isolated tree, so two tasks editing code can't collide with each other or with the parent.

The collision that matters is git: commits sweep up everything in a tree, so two agents committing on one shared machine can capture each other's half-done edits. Fresh machines make that impossible by construction. The same rule has a hard corollary: **two agents must never push the same branch.** The second push clobbers or conflicts with the first. Parallel tasks ship separate branches; overlapping work stacks instead.

## Parallel vs stacked

* **Parallel** tasks run simultaneously and must touch disjoint parts of the codebase: different packages, different files. Each ships its own PR.
* **Stacked** tasks depend on each other or touch overlapping files: Task 1 runs and ships its PR, then Task 2 starts from Task 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 tasks costs more than the waiting.

## Task 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 task is just an idle task. |
| `done`                | Delivered a final result to the parent.                               |
| `failed`              | Ended in an unrecoverable error.                                      |

No resting state is terminal in practice: messaging any resting task reopens it. A `done` task woken by CI on its own PR can fix the failure and deliver a fresh result.

## How results come back

A task reports to its parent through explicit messages, and only the endings travel automatically:

* A task that finishes delivers its final summary to the parent, which wakes and acts on it.
* A task 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 task.

## Reviewing and shipping task work

A completed task's work sits on its machine until someone ships it. The parent reviews by inspecting the diff on the task's machine, then either opens a PR from the task's branch, patches small problems itself, or sends the task targeted feedback and lets it revise. You can direct any of this: "check Task 2's diff before opening the PR" or "tell Task 1 the API changed and have it rebase."

Only pushed or PR'd work survives: task machines are as ephemeral as any other, so a task that ends without shipping leaves nothing durable but its summary.

## Models per task

Each task can run on its own model: a cheaper model for mechanical work, a stronger one for a gnarly refactor, or a subscription-billed seat (like a connected Codex subscription) that costs your org nothing extra per token. By default tasks inherit the thread's model; ask for a specific split when you want one: "run the test-writing tasks on the cheapest reasonable model."

## Coordinating across threads

Tasks 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, tasks, and PRs) and message them. The difference from tasks: nothing reports back automatically. 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 tasks.

## Prompts that orchestrate well

Parallel split across disjoint files:

```text theme={null}
Migrate our API handlers from Express to Fastify. Split it into parallel tasks by directory (one task each for routes/auth, routes/billing, and routes/webhooks) on fresh machines, each shipping its own PR. Give every task 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: Task 1 builds the audit_log table, migration, and write API, and ships a PR. When that PR is up, start Task 2 from Task 1's branch to wire logging into the settings and members endpoints, as a second PR on top. Review Task 1's diff before starting Task 2.
```

Cheap parallel audit, shared machine:

```text theme={null}
Before we cut the release: spawn three read-only tasks 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.
```