Skip to main content
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. Tasks are cheap parallelism precisely because they don’t drag the whole conversation context with them.

​
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.
Capy must choose one explicitly whenever it starts a task. The start result names the placement and machine id, so a mismatch is visible before the child reports missing files.

​
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

​
How results come back

A task reports to its parent through explicit messages:
  • 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.”

​
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). 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. 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:
Stacked feature where the pieces overlap:
Cheap parallel audit, shared machine: