This is the reference half of Multi-Agent Orchestration with Orca. It is written for the agent, not the reader — lift what you need into AGENTS.md, CLAUDE.md, or whatever instructions file your coding agents load.

Everything here was verified against a live orca CLI. Verify it again against yours before trusting it: flags move between versions, and the CLI publishes its own schema for exactly this reason.

On Linux, orca is also the GNOME screen reader. Inside an Orca-managed terminal the orca command resolves correctly; outside one, use orca-ide.

Discovery first

Never hard-code a command list into a prompt. Have the agent ask the binary:

orca agent-context --json     # machine-readable schema of every command + flag
orca <group> --help           # per-group flags
orca skills list --json       # bundled skill guides
orca skills get orca-cli      # read one before installing it

agent-context works even when the desktop runtime is unreachable, which makes it the right thing to consult before writing any command down.

Readiness

orca status --json

Treat as ready only when all three hold:

Field	Expected
`app.running`	`true`
`runtime.reachable`	`true`
`runtime.state`	`ready`

Also read capabilities. Runtimes differ by version and host, and it is the honest way to establish what this one supports rather than assuming. A headless host, for example, will not expose the hosted merge-request surface.

Setup

orca account add --agent claude          # interactive sign-in; host-local
orca account add --agent codex
orca repo add --path /abs/path --json    # copy the exact selector from the JSON
orca repo list --json

orca account add covers the Claude and Codex sign-ins. It is not a general installer — any other agent CLI must already be installed and working on that host, or the dispatch dies at launch.

Worktrees

orca worktree create --repo id:<repo-id> --name <slice> --base-branch main --json
orca worktree list --repo id:<repo-id> --json
orca worktree ps --json
orca worktree set --worktree <selector> --workspace-status in-review --comment "<text>"

Selectors accept id:<repo-id>::<path>, name:<displayName>, branch:<branch>, path:<path>, or current.

The full worktree ID has two parts: <repo-id>::<worktree-path>. Preserve the whole value when addressing a checkout. Truncating it is the single most common way an agent addresses the wrong slice.

Terminals

orca terminal create --worktree <selector> --title "<name>" --command "codex" --json
orca terminal read   --terminal <handle> --json
orca terminal send   --terminal <handle> --text "<input>" --enter --json
orca terminal wait   --terminal <handle> --for tui-idle --timeout-ms 300000 --json
orca terminal close  --terminal <handle> --json

Read before you send. The worker may be answering a prompt, waiting on a permission, or already reporting a failure; typing blindly into that corrupts the interaction.

Use --for tui-idle for a long-running agent and --for exit for a finite command. Do not guess a sleep.

Orchestration

orca orchestration run-create   --objective "<what this run is for>" --json
orca orchestration task-create  --run <run-id> --task-title "<title>" --spec "<brief>" --json
orca orchestration worker-start --run <run-id> --task <task-id> \
    --agent <agent> --worktree <selector> --json
orca orchestration worker-list  --run <run-id> --json
orca orchestration worker-read  --dispatch <dispatch-id> --json

Add --on <saved-environment> to place a worker on another machine while the run and inbox stay with the coordinator.

Workers close with an explicit state — this is what lets a coordinator react to an outcome instead of inferring one from silence:

orca orchestration send --type worker_done --outcome succeeded --run <run-id> --body "<summary>"
orca orchestration send --type worker_done --outcome failed    --run <run-id> --body "<what broke>"

Gates block a task until a human decides:

orca orchestration gate-create
orca orchestration gate-list
orca orchestration gate-resolve

Lifecycle verbs that are easy to confuse

Verb	Use when
`worker-stop`	The process is proven dead
`worker-abandon`	Its state is uncertain — never claims it stopped
`worker-release`	It settled and you want the terminal back
`worker-retain`	Keep the terminal alive for debugging

Worker brief template

Give every worker its constraints in writing. This shape has worked well:

Read <brief-path> first and follow every constraint in it.

SLICE <id> — <one-line objective>.

Write output only to: <exact path>

Cover:
1. <point>
2. <point>

Verify every command and flag you document against `<tool> --help`
before writing it. Do not invent flags.

Do not edit any file outside your assigned path.
Do not commit, push, or open a merge request.

When finished:
  orca orchestration send --type worker_done --outcome succeeded \
    --run <run-id> --body "<what you produced>"

Two details do a lot of work here. Naming an exact output path lets several workers share one worktree without conflicting. Forbidding commits and merge requests keeps integration with the coordinator, which is where the review judgement lives.

Conventions worth encoding

One worktree per parallel slice; no edits outside the assigned slice.
Read a terminal before sending input to it.
Verify commands against --help or agent-context; never invent flags.
Report tests run, files changed, and remaining uncertainty — not just success.
Credentials never enter repositories, instruction files, or command lines.
A worker_done message is a routing signal, not proof of correctness.

Failure modes seen in practice

Symptom	Cause	Response
Dispatch fails at launch	The agent CLI is not installed on that host	Check the host’s roster before routing
`agent_prompt_stalled`	The TUI never accepted the injected prompt	Relaunch, or run the CLI headless in a managed terminal
Provider returns repeated 5xx	Upstream outage	Cut that provider from the run rather than retrying into it
Worker goes quiet	No explicit outcome was reported	Read the terminal; abandon rather than assume it stopped
Hosted review unavailable	Headless host does not expose that surface	Check `capabilities` first; report the gap instead of faking the result

Multi-Agent Orchestration with Orca — the guide this reference belongs to
AI agent reliability: failure modes, controls, and evidence

Discovery first

Readiness

Setup

Worktrees

Terminals

Orchestration

Lifecycle verbs that are easy to confuse

Worker brief template

Conventions worth encoding

Failure modes seen in practice

Related