Claw Orchestrator

Claw Orchestrator Skill

Claw Orchestrator — persistent multi-engine coding session manager for claw-style agent systems. Runs as a standalone CLI/server, with first-class OpenClaw plugin support. Wraps Claude Code, Codex, Antigravity, Grok Build, OpenCode, and custom CLIs into headless agentic engines with 77 tools.

Engine Quick Reference

Core Workflow

// 1. Start session (any engine)
session_start({ name: 'myproject', cwd: '/path/to/project', engine: 'claude' });
session_start({ name: 'codex-task', cwd: '/path/to/project', engine: 'codex' });
session_start({ name: 'agy-task', cwd: '/path/to/project', engine: 'agy' });
session_start({ name: 'grok-task', cwd: '/path/to/project', engine: 'grok' });
session_start({
  name: 'opencode-task',
  cwd: '/path/to/project',
  engine: 'opencode',
  model: 'anthropic/claude-sonnet-4',
});

// 2. Send messages
session_send({ name: 'myproject', message: 'Fix the auth bug' });

// 3. Check status / search history
coding_session_status({ name: 'myproject' });
session_grep({ name: 'myproject', pattern: 'error' });

// 4. Stop when done
session_stop({ name: 'myproject' });

Session Options

CLI 2.1.111 options

CLI 2.1.121 options

stats.pluginErrors is now populated from the system/init event when CLI plugins fail to load due to unmet dependencies.

TRACEPARENT / TRACESTATE (W3C distributed tracing) are automatically forwarded from parent process env — set them before starting the session and they propagate to the child Claude CLI.

Smart defaults: When bare: true, the plugin auto-enables --exclude-dynamic-system-prompt-sections and ENABLE_PROMPT_CACHING_1H=1 unless explicitly set to false.

Multi-Agent Council

Parallel agent collaboration with git worktree isolation and consensus voting. Agents can use different engines.

// Start a council
council_start({
  task: 'Build a REST API',
  agents: [
    { name: 'Architect', emoji: '🏗️', persona: 'System design', engine: 'claude' },
    { name: 'Engineer', emoji: '⚙️', persona: 'Implementation', engine: 'codex' },
  ],
  maxRounds: 5,
  projectDir: '/path/to/project',
});

Council lifecycle: council_start → poll council_status → council_review → council_accept or council_reject.

For details: see references/council.md

Cross-Session Messaging

Sessions can communicate. Idle sessions receive immediately; busy sessions queue.

session_send_to({ from: 'sender', to: 'receiver', message: 'Auth module needs rate limiting' });
session_send_to({ from: 'monitor', to: '*', message: 'Build failed!' }); // broadcast
session_inbox({ name: 'receiver' });
session_deliver_inbox({ name: 'receiver' });

Team Tools (All Engines)

All engines use the same virtual-team layer: cross-session inbox routing across active SessionManager sessions. (Claude Code's native experimental Agent Teams is in-process TUI only and not reachable from a subprocess wrapper.)

team_list({ name: 'myproject' });
team_send({ name: 'myproject', teammate: 'teammate', message: 'Review this' });

Ultraplan & Ultrareview

• Ultraplan: Opus deep planning session (up to 30 min), produces detailed implementation plan
• Ultrareview: Fleet of 5-20 bug-hunting agents reviewing in parallel (security, logic, perf, types, etc.)

Both are async — start then poll status.

Autoloop (autonomous workspace iteration)

Autoloop uses three persistent roles. You chat with the Planner to define plan.md and goal.json; after explicit approval it starts a Coder/Reviewer iteration loop. Each role may use a different engine.

autoloop_start({
  run_id: 'fix-parser',
  workspace: '/path/to/repo',
  planner_engine: 'claude',
  coder_engine: 'codex',
  reviewer_engine: 'agy',
});
autoloop_chat({ run_id: 'fix-parser', text: 'Read the repo and design a plan to fix the parser.' });
autoloop_chat({ run_id: 'fix-parser', text: 'Plan approved; start the loop.' });
autoloop_status({ run_id: 'fix-parser' });
autoloop_stop({ run_id: 'fix-parser', reason: 'done' });

Claude roles default to Planner opus and Coder/Reviewer sonnet. A non-Claude role with no model uses that engine's own default. Custom engine configs are supplied only at start (or HTTP resume), never by Planner output. The Reviewer runs in a restaged sandbox and returns advance/hold/rollback verdicts; push policy and SSE keep long runs observable.

For the full control protocol, registry/resume behavior, and ledger layout, see references/autoloop.md.

Tools Overview

ultracode (Claude dynamic workflows) is a session_start option, not a separate tool: set ultracode: true to have Claude orchestrate a JS workflow and fan out to subagents per task.

For full parameter reference: see references/tools.md

Run as an ACP agent

clawo acp (or the clawo-acp binary) serves Agent Client Protocol over stdio, so any ACP client — Zed, JetBrains, Neovim, Emacs, the VS Code ACP extension, or dsh through its subagent-acp provider — drives the orchestrator as its coding agent. The model selector is grouped by engine, so one dropdown spans Claude, Codex and Cursor and switching it switches engine mid-session.

For setup, the dsh YAML block, and the cancellation/permission limits: see references/acp.md

Durable workflows

workflow_start runs a declarative graph of agent / fanout / council / verifier / human_gate / router / subflow nodes. Every state transition is checkpointed to ~/.claw-orchestrator/wf/<runId>/, so a run survives a process restart and workflow_resume picks it up at the node boundary — nodes already succeeded are not re-run, and the one that was in flight is retried because a half-finished node left no result to trust.

Three built-in templates: solve (triage → implement → verify → repair-until-green → review), council, and fanout. Retry, per-node timeout, cancel, steer, human gates, and bounded loops come from the kernel rather than from each mode's own state machine.

For node shapes, routing conditions, and the control surfaces: see references/workflow.md

Verification — does the work actually pass?

Hand a run an acceptance contract and the runtime checks the result itself: shell commands gated on exit code, HTTP probes, headless-Chrome screenshots, diff policy, file assertions. A run carrying a contract cannot reach completed unless every required check passes; a run without one completes as unverified, which says nothing checked it rather than claiming success. Every attempt writes an evidence bundle — verdict, per-check output tails, the patch (created files included), screenshots — readable later with clawo verify <runId>.

Contracts come from the caller or a mode default, never from agent output: an agent that writes its own acceptance criteria is grading itself. UltraApp ships one on by default; verify_run checks work that did not come through a workflow at all.

For the check types, per-mode defaults, and what the screenshot gate does and does not claim: see references/verification.md

Cost & spend caps

Every turn on every engine is appended to a durable ledger at ~/.claw-orchestrator/runs/YYYY-MM-DD.jsonl — engine, model, per-turn tokens, cost, duration, and the council / fanout / autoloop it belonged to. Query it with clawo runs [--since 24h] [--engine X] [--parent <run id>] [--json], GET /runs, or manager.getRunLedger(); it survives restarts, so it answers "what did we run today and what did it cost" after the sessions are gone.

maxBudgetUsd on a session (or per council / fanout agent) is enforced by the runtime, so it holds on Codex, Cursor, agy, OpenCode and custom engines too — not just Claude Code. Once cumulative spend reaches the cap, further sends are refused before the engine is spawned.

Rows carry two different judgements and keep them apart: ok is the engine's terminal verdict on its own turn, verified is whether an acceptance contract passed. A row with no verified at all means no contract was declared — not that it failed. clawo runs --verified / --refuted filter on it.

For the row schema, the query surfaces, and which engines report real token usage versus estimating it: see references/observability.md

Authentication Prerequisites

Each engine requires its own auth before use:

• Claude: claude /login or ANTHROPIC_API_KEY
• Codex: codex login or OPENAI_API_KEY
• Antigravity: run agy once and complete the Google OAuth login
• Grok: run grok once and sign in (grok.com account or XAI_API_KEY)
• OpenCode: opencode auth login (provider-agnostic; use provider/model form for model)