Orchestration
Coordinate agents with Runs, tasks, supervised workers, messages, and decision gates.
Orchestration is Nethür'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. For one-off prompts, use nethur terminal send. For full ownership handoffs without supervision, use worktree/terminal commands from the nethur-cli skill.
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/ heartbeat. - 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 and heartbeat messages should include both taskId and dispatchId.
Task IDs printed in terminals, such as task_..., are clickable links. Clicking one asks the Nethür 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
nethur orchestration run-create --objective "Split checkout QA and summarize blockers" --json
nethur orchestration task-create --spec "Audit billing settings for mobile layout" --task-title "Billing audit" --json
nethur orchestration worker-start --task <taskId> --worktree current --agent codex --json
# or new worktree:
nethur orchestration worker-start --task <taskId> --worktree new-child --name billing-audit --agent codex --setup run --json
# optional per-worker model / effort (Claude, Codex, Cursor, Antigravity, Muse; not with --terminal):
nethur orchestration worker-start --task <taskId> --worktree current --agent claude --model <opaque-model-id> --effort high --json--agent takes any Nethür 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, and Muse (for example --agent muse --model muse-spark-1.3); 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 under launch.requested / launch.effective in the start receipt. Federated starts need a worker host that advertises launch-preference support.
Wait for completions (process every message in a Delivery, then ack):
nethur orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
nethur orchestration check --ack <deliveryId> --wait --types worker_done,escalation,question --timeout-ms 900000 --jsonWorker completion (from the worker pane; include injected IDs):
nethur 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" \
--jsonworker_done requires --outcome succeeded|failed.
Inspect / recover:
nethur orchestration worker-show --dispatch <dispatchId> --json
nethur orchestration worker-read --dispatch <dispatchId> --limit 50 --json
nethur orchestration worker-stop --dispatch <dispatchId> --json
# 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):
nethur orchestration worker-release --dispatch <dispatchId> --json
# Keep a settled worker live for debugging when the user asked to retain it:
nethur orchestration worker-retain --dispatch <dispatchId> --json
# retry placement is explicit — --retry-of does not inherit --on/worktree:
nethur orchestration worker-start --task <taskId> --retry-of <dispatchId> --worktree current --agent codex --jsonDo 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)
nethur orchestration worker-start \
--task <taskId> \
--on windows \
--worktree new-top-level \
--repo <exact_remote_repo_selector> \
--name remote-worker \
--agent codex \
--setup run \
--json
nethur orchestration send --to dispatch:<dispatchId> --subject "Follow-up" --body "…" --jsonLater commands route by Dispatch ID; do not repeat --on.
Low-level dispatch (custom topology)
nethur worktree create --name billing-audit --agent codex --json
nethur terminal wait --terminal <workerHandle> --for tui-idle --timeout-ms 60000 --json
nethur orchestration dispatch --task <taskId> --to <workerHandle> --inject --jsonMessaging notes
- Default
checkis the bound Run's oldest unacked Delivery (FIFO). Replay until--ack. --peek/--alldo not consume mail.- Group addresses:
@all,@idle,@claude,@codex,@opencode,@gemini,@droid,@grok,@cursor,@worktree:<id>— never forworker_done/ heartbeat. - 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".
nethur orchestration send --to @all --subject "Heads up" --body "Pausing dispatches for a review." --json
nethur orchestration send --to @idle --subject "Anyone free?" --json
nethur orchestration send --to @codex --subject "Codex workers in this Run only" --jsonWhile 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.
- Send
heartbeatmessages during long active work. - Use
nethur orchestration askfor blocking questions instead of local TUI prompts.
nethur orchestration ask \
--to <coordinatorHandle> \
--question "Should I update the shared component or only this page?" \
--options "shared,page-only" \
--timeout-ms 600000 \
--jsonWith --json, ask prints the standard {id, ok, result, _meta} envelope, so workers read the answer 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:
nethur orchestration gate-create \
--task <taskId> \
--question "Merge the shared button change into the task branch?" \
--options '["yes","no"]' \
--json
nethur orchestration gate-resolve --id <gateId> --resolution "yes" --jsonRecovery
nethur orchestration dispatch-show --task <taskId> --json
nethur orchestration dispatch-show --task <taskId> --preamble --json
nethur orchestration task-list --json
nethur orchestration task-update --id <taskId> --status blocked --result '{"reason":"waiting on credentials"}' --jsonReset only when you are intentionally abandoning orchestration state:
nethur orchestration reset --tasks --json
nethur orchestration reset --messages --json
nethur orchestration reset --all --jsonreset 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 nethur terminal send for a lightweight prompt to an agent you are watching.
Use nethur 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 nethur 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:
nethur skills get orchestration --full