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 78 tools.

Engine Quick Reference

Engine	CLI	Session Type	Best For
claude	claude	Persistent subprocess	Multi-turn, complex tasks
codex	codex exec	Per-message spawn	One-shot execution
agy	agy -p	Per-message spawn	Google Antigravity; plain-text, auto conversation resume
grok	grok -p	Per-message spawn	xAI Grok Build; engine-reported cost, resumable session
opencode	opencode run	Per-message spawn	Provider-agnostic (provider/model)

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-5',
});

// 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

Parameter	Description
engine	claude (default), codex, agy, grok, opencode, custom
model	Model name or alias (fable, opus → claude-opus-5-5, sonnet, haiku, gpt-5.5, agy-pro)
permissionMode	acceptEdits, auto, plan, bypassPermissions, manual, dontAsk (default = legacy alias for manual)
effort	low, medium, high, xhigh, max, ultra, auto (each engine clamps to its own ceiling)
maxBudgetUsd	Cost limit in USD
allowedTools	List of allowed tool names

Claude-engine options

Parameter	Description
bare	Minimal mode — no CLAUDE.md, hooks, LSP, auto-memory. Auto-enables prompt cache optimizations (see below).
includeHookEvents	Stream hook lifecycle events (PreToolUse/PostToolUse).
forwardSubagentText	Forward subagent text and thinking into the output stream, so sessions that fan out surface intermediate output instead of going quiet.
permissionPromptTool	Delegate permission prompts to an MCP tool for non-interactive use.
excludeDynamicSystemPromptSections	Move cwd/env/git from system prompt to user message for better prompt cache hits. Auto-enabled with bare: true.
enablePromptCaching1H	Enable 1-hour prompt cache TTL (vs default 5-min). Auto-enabled with bare: true.
debug / debugFile	Targeted debug output by category (e.g. "api,mcp") and optional file path.
fromPr	Resume a session linked to a GitHub PR number or URL.
channels / dangerouslyLoadDevelopmentChannels	MCP channel subscriptions (research preview).
forkSubagent	Fork subagent for non-interactive sessions (sets CLAUDE_CODE_FORK_SUBAGENT=1).
enableToolSearch	Enable Vertex AI tool search (sets ENABLE_TOOL_SEARCH=1).
otelLogUserPrompts	OpenTelemetry: include user prompts in logs (sets OTEL_LOG_USER_PROMPTS=1).
otelLogRawApiBodies	OpenTelemetry: include raw API bodies in logs (sets OTEL_LOG_RAW_API_BODIES=1). Debug only.

stats.pluginErrors lists CLI plugins that failed to load (from the system/init event).

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: 1-20 read-only reviewer agents (default 5) running in parallel, each from one angle (security, logic, perf, types, etc.), merged by a synthesis pass

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

Category	Tools
Session Lifecycle	session_start, session_send, session_handoff, session_stop, session_list, sessions_overview
Session Ops	coding_session_status, session_grep, session_compact, session_update_tools, session_switch_model, project_purge
Inbox	session_send_to, session_inbox, session_deliver_inbox
Teams	coding_agents_list, team_list, team_send
Codex	codex_resume, codex_review, codex_goal_*, codex_interrupt, codex_steer, codex_fork, codex_rollback, codex_models, codex_thread_list
Claude CLI	claude_goal_*, claude_agents_list, plugin_details
Fan-out	fanout_start, fanout_status, fanout_abort
Council	council_start, council_status, council_abort, council_inject, council_review, council_accept, council_reject
Ultra	ultraplan_start, ultraplan_status, ultrareview_start, ultrareview_status
Autoloop	autoloop_start, autoloop_chat, autoloop_status, autoloop_list, autoloop_stop, autoloop_reset_agent
Workflow & verify	workflow_start, workflow_status, workflow_list, workflow_resume, workflow_cancel, workflow_steer, workflow_approve, verify_run
Ultraapp	ultraapp_new, ultraapp_answer, ultraapp_add_file, ultraapp_spec_edit, ultraapp_build_start, ultraapp_build_cancel, ultraapp_status, ultraapp_get, ultraapp_list, ultraapp_feedback, ultraapp_promote_version, ultraapp_start_container, ultraapp_stop_container, ultraapp_delete

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, Antigravity and Grok, 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 / autoloop / ultraapp_synth / ultraapp_deploy 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, agy, Grok, 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)