Orchestration

Coordinate agents with Runs, tasks, supervised workers, messages, and decision gates.

Orchestration is Orca's structured multi-agent layer: a Run (namespace + coordinator inbox), Tasks, Dispatches, supervised workers, messages, and decision gates.

Use it when you need ownership, completion tracking, or a DAG. To send another agent a one-way message, use orca orchestration send --to <terminal handle or orca_session_id:<id>> --subject "<topic>" --body "<message>"; it needs no Run or Task. For full ownership handoffs without supervision, use worktree create --agent or agent launch from the orca-cli skill.

Output

Every orchestration command prints a short view by default: the IDs and state the next command needs, with the next step last. --json prints the same fields as one line of JSON ({"ok":true,"result":{...}}). --full --json prints the complete record Orca returned as pretty JSON; --full alone prints the longer text receipt. A failed or unconfirmed outcome exits non-zero and writes error: <code>: <message> to stderr.

Core model

  • Run — durable namespace and home inbox. Never schedules or places workers.
  • Task — a work item with a spec, dependencies, and status: pending, ready, dispatched, completed, failed, or blocked.
  • Dispatch — one attempt of a task on a terminal; lifecycle authority for worker_done.
  • Message — inbox mail (status, dispatch, worker_done, escalation, question, heartbeat, …).
  • Decision gate — a coordinator-owned question that blocks a task until it is resolved.

Completion authority comes from the active dispatch context. Worker completion messages should include both taskId and dispatchId.

Task IDs printed in terminals, such as task_..., are clickable links. Clicking one asks the Orca runtime for the task's current dispatch and focuses the assigned terminal, including when the task lives in a remote or SSH runtime.

Preferred supervised loop

orca orchestration run-create --objective "Split checkout QA and summarize blockers"
orca orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit"
orca orchestration worker-start --task <taskId> --worktree current --agent codex
# or new worktree:
orca orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run
# optional per-worker model / effort (Claude, Codex, Cursor, Antigravity, Grok, Muse, Pi; not with --terminal):
orca orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high

--agent takes any Orca agent ID enabled on the worker server, for example claude, codex, cursor, antigravity, muse, opencode, or opencode2. --model accepts opaque provider model IDs for Claude, Codex, Cursor, Antigravity, Grok, Muse, and Pi (for example --agent muse --model muse-spark-1.3); Pi takes a provider/id selector and maps --effort to its own --thinking level (off, minimal, low, medium, high, xhigh, max); OpenCode accepts a per-launch model only in an existing worktree, when the execution host verifies its CLI version and model availability; OpenCode effort remains unsupported. Other agents run the model from their own config. --effort requires --model and only applies when that agent/model supports the level. Neither flag can combine with --terminal (reuse an existing pane). Overrides apply to that launch only and show as model / effort in the start receipt (--full --json shows launch.requested / launch.effective). Federated starts need a worker host that advertises launch-preference support.

After starting workers, end your turn. Orca wakes the coordinator when a worker reports, asks, or stops. In a chat, each message arrives whole: act on it. When the wake names a check command (a terminal, or a chat message too large to deliver whole), run it and handle every message it prints:

orca orchestration check --run <runId>

Worker completion (from the worker pane; include injected IDs):

orca orchestration send \
  --type worker_done \
  --subject "Completed mobile audit" \
  --body "Fixed footer overlap; no follow-ups." \
  --task-id <taskId> \
  --dispatch-id <dispatchId> \
  --outcome succeeded \
  --files-modified "src/app/settings/Billing.tsx"

worker_done requires --outcome succeeded|failed.

Inspect / recover:

orca orchestration worker-show --dispatch <dispatchId>
orca orchestration worker-read --dispatch <dispatchId> --limit 50
orca orchestration worker-stop --dispatch <dispatchId>
# After an accepted worker_done: reuse the same terminal for a follow-up Dispatch, or release it
# (archives inspectable output, then closes only that coordinator-owned agent terminal):
orca orchestration worker-release --dispatch <dispatchId>
# Keep a worker open after it finishes (or start it with worker-start --keep-open):
orca orchestration worker-keep-open --dispatch <dispatchId>
# retry placement is explicit — --retry-of does not inherit --on/worktree:
orca orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex

When a worker stops at a permission prompt, the escalation names the prompt. Only a person can allow it, so carry on with other work until its closing message arrives; if it is holding up the task, deny it with a reason and the worker carries on another way:

orca orchestration deny --dispatch <dispatchId> --prompt <approvalId> --reason "<what to do instead>"

If the user turns on Let coordinators approve worker permission prompts in Orca's orchestration settings, the coordinator may also allow it with a reason. The user still sees Allow and Deny, and the first answer wins. The machine running the worker applies its own setting:

orca orchestration approve --dispatch <dispatchId> --prompt <approvalId> --reason "<reason>"

Do not leave completed worker terminals open just to re-read output — use worker-read after worker-release. Do not substitute a broad terminal close when release returns release_pending or release_unknown; follow the receipt's recovery action.

Federated workers (optional)

orca orchestration worker-start \
  --task <taskId> \
  --on windows \
  --worktree new-top-level \
  --repo <exact_remote_repo_selector> \
  --name remote-worker \
  --agent codex \
  --setup run
orca orchestration send --to dispatch:<dispatchId> --subject "Follow-up" --body "…"

Use --worktree new-child instead to nest the server's worktree under your workspace in the sidebar. A server too old to nest across machines still starts the worker, top-level, with a warning in the receipt.

Later commands route by Dispatch ID; do not repeat --on.

Low-level dispatch (custom topology)

orca worktree create --name billing-audit --agent codex --json
orca terminal wait --terminal <workerHandle> --for tui-idle --timeout-ms 60000 --json
orca orchestration dispatch --task <taskId> --to <workerHandle> --inject

Messaging notes

  • Default check returns the bound Run's oldest unread mail as one Delivery (FIFO) and marks it handled. --ack <deliveryId> acknowledges a Delivery from an older Orca that does not mark it; alone it reads no new mail, and with --wait it then waits for and takes the next Delivery.
  • --peek / --all do not consume mail and return no deliveryId, so they do not drain a mailbox on their own. --all and a Run --peek show at most 100 rows. To drain, repeat plain check until it prints No messages. (with --json, until messages is empty); on an older Orca that asks for --ack <deliveryId>, ack each Delivery first or check returns it again.
  • Group addresses: @all, @idle, @claude, @codex, @opencode, @gemini, @droid, @grok, @cursor, @worktree:<id> — never for worker_done.
  • Every group except @worktree:<id> means the live Dispatches of the sender's own Run, delivered to their Dispatch mailboxes (or child Run mailboxes for nested coordinators). A sender in no Run is refused; --run must match the audience and never grants membership.
  • Run groups exclude their owning coordinator. A worker raising a blocker sends to run:<id>. @worktree:<id> includes coordinators in that workspace.
  • Quote PowerShell group addresses: --to "@all".
orca orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review."
orca orchestration send --to @idle --subject "Anyone free?"
orca orchestration send --to @codex --subject "Codex workers in this Run only"

While a wait is active, the CLI emits small JSON heartbeat lines to stderr every 15 seconds. Stdout remains the final command result.

Worker contract

Dispatched workers receive a preamble that tells them how to communicate with the coordinator:

  • Send worker_done exactly once, even on failure, with --outcome.
  • Include a short --body summary: what was done, what was found, and what remains.
  • Include both task and dispatch IDs so stale retries cannot complete the wrong dispatch.
  • Use orca orchestration ask for questions instead of local TUI prompts, then end your turn. Orca wakes you with the answer as mail: in a chat it arrives whole, unless it is too large for one chat message; whenever the wake names a check command, run it.
orca orchestration ask \
  --question "Should I update the shared component or only this page?" \
  --options "shared,page-only"

ask records the question and returns at once with pending: true. Add --wait (or --resume <message_id>) to block until the answer instead; with --json, read it with jq -r .result.answer.

Decision gates

Use ask for worker-to-coordinator questions. Use explicit gates when the coordinator has created a task DAG and wants to block a task until a decision is recorded:

orca orchestration gate-create \
  --task <taskId> \
  --question "Merge the shared button change into the task branch?" \
  --options '["yes","no"]'

orca orchestration gate-resolve --id <gateId> --resolution "yes"

Recovery

orca orchestration dispatch-show --task <taskId>
orca orchestration dispatch-show --task <taskId> --preamble
orca orchestration task-list
orca orchestration task-update --id <taskId> --status blocked --result '{"reason":"waiting on credentials"}'

Reset only when you are intentionally abandoning orchestration state:

orca orchestration reset --tasks
orca orchestration reset --messages
orca orchestration reset --all

reset affects runtime-global orchestration state. Do not run it while another coordinator is active unless that is the intended cleanup.

Choosing the right command

Use orca orchestration send for a one-way message to another agent. For ordinary mail, a chat receives the whole message with its sender header (a message too large for one chat message gets a note to run orca orchestration check instead), Orca never types your words into a terminal agent's input (it reads mail through check), and the receipt means the mail was stored, not read. A send to a finished worker's dispatch:<id> can instead start a follow-up Task, whose body the worker gets as its task; the receipt says which. Use orca terminal send for shells, dev servers and REPLs, never to message an agent.

Use orca orchestration worker-start (or dispatch --inject) when a worker must report worker_done, ask questions through the coordinator, and be tracked by task ID.

Use orca orchestration run-create + tasks + workers when you want a durable Run namespace and supervised multi-agent loop — not the retired orchestration run command.

Full guide

Command flags evolve with the app. After install, agents should run:

orca skills get orchestration --full