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, orblocked. - 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
checkreturns 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--waitit then waits for and takes the next Delivery. --peek/--alldo not consume mail and return nodeliveryId, so they do not drain a mailbox on their own.--alland a Run--peekshow at most 100 rows. To drain, repeat plaincheckuntil it printsNo messages.(with--json, untilmessagesis empty); on an older Orca that asks for--ack <deliveryId>, ack each Delivery first orcheckreturns it again.- Group addresses:
@all,@idle,@claude,@codex,@opencode,@gemini,@droid,@grok,@cursor,@worktree:<id>— never forworker_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;--runmust 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_doneexactly once, even on failure, with--outcome. - Include a short
--bodysummary: 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 askfor 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 acheckcommand, 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