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

# Multi-agent orchestration

> Coordinate coding agents with messages, task dispatch, results, heartbeats, and human decision gates.

Several terminals do not become a team just because they share a screen. Dure
adds a coordination layer so agents can hand work to one another, report
results, raise blockers, and wait for a human decision without depending on a
single provider.

## Before you run the commands

* Install the `dure` CLI and launch Dure at least once in the app channel you
  intend to use. This creates the registry the CLI reads. After that,
  `task-create` does not require the app to be running.
* `task-create` only records a task. It needs a `--title`, but no provider,
  live agent, project, worktree, or managed session. `--spec` and `--deps` are
  optional.
* There is no separate `--requirements` field. Put scope, acceptance criteria,
  validation, and the expected result format in the free-form `--spec`. Dure
  stores and delivers it but does not judge whether the contract is complete.
* A terminal opened inside Dure inherits the correct app channel. The installed
  app defaults to `stable`; an external shell targeting an isolated development
  build must set `DURE_APP_CHANNEL` to that build's channel.
* `dispatch --inject` has stricter requirements: the target must be registered
  in the same channel and its session must be able to receive input. A complete
  report-back loop currently needs a local target because remote mailboxes are
  not bridged. Without `--inject`, dispatch persists the assignment and message
  only.

## What the coordination layer adds

<CardGroup cols={2}>
  <Card title="Typed messages" icon="messages-square">
    Send notes, status updates, dispatches, completion reports, escalations,
    decision gates, and heartbeats.
  </Card>

  <Card title="Provider-neutral targets" icon="waypoints">
    Address one agent, everyone with `@all`, or a provider group such as
    `@claude` or `@codex`.
  </Card>

  <Card title="Tasks with results" icon="list-checks">
    Record a task, assign it to an agent, and receive a structured
    `worker_done` result instead of guessing from terminal output.
  </Card>

  <Card title="Human decisions in the loop" icon="split">
    Agents can ask a blocking question or open a decision gate before crossing
    a boundary that needs approval.
  </Card>
</CardGroup>

Messages and task state are persisted in the current Dure app channel. Inside a
managed agent session, Dure identifies the sender automatically, so ordinary
agent commands do not need a separate `--from` identity.

## A small coordination loop

Send an announcement to the active team:

```sh theme={"system"}
dure orch send --to @all \
  --subject "Switch candidates asynchronously" \
  --body "Stop tracking origin/main and report blockers to the coordinator."
```

Create a task and dispatch it to a named agent:

```sh theme={"system"}
dure orch task-create \
  --title "Review the session recovery diff" \
  --spec "Scope: recovery diff. Verify behavior, tests, and rollback paths. Output: findings only."

# Replace t7 with the ID printed by task-create.
dure orch dispatch --task t7 --to review-agent --inject
```

`--inject` places the task brief and reporting protocol into that agent's
terminal. The dispatch is also kept as a typed message, so it is more than raw
keystroke delivery.

Wait for results, escalations, or decisions that need attention:

```sh theme={"system"}
dure orch check --wait \
  --types worker_done,escalation,decision_gate \
  --timeout 900
```

## Coordination patterns

### Fan out independent work

Create separate tasks for research, implementation, and review, then dispatch
each one to a different agent or provider. Worktrees isolate file changes while
the orchestration channel carries the shared intent and results.

### Ask instead of silently blocking

An agent that needs a coordinator's answer can wait for a reply:

```sh theme={"system"}
dure orch ask --to coordinator \
  --question "Should the fallback preserve the legacy session?" \
  --options "preserve,replace"
```

### Distinguish slow work from a stuck agent

Long-running workers can send `heartbeat` messages. Work that cannot continue
can send an `escalation`, making the difference visible without someone
watching every terminal.

## How this differs from terminal injection

Typing text into another terminal is useful for waking an agent or delivering a
prompt, but it has no task identity, message type, or durable result contract.
Dure orchestration records the communication first. Injection is an optional
delivery aid for a dispatched task, not the source of truth.

<Warning>
  Orchestration is currently local to one Dure app channel. Remote SSH agents do
  not directly join the local mailbox, and `@all` does not yet keep a separate
  delivery acknowledgement for each recipient. Use explicit recipients for
  required actions.
</Warning>

See [current limits](/en/current-limits) for the exact alpha boundary, or read
[provider support](/en/providers) to choose workers for a task.