--- name: Claw Orchestrator slug: claw-orchestrator category: AI Engineering description: Claw Orchestrator manages persistent coding sessions across Claude Code, Codex, Antigravity, Grok Build, and OpenCode. Use it to start, send to, stop, and coordinate multi-engine agent runs, including council, review, and planning workflows. github: "https://github.com/Enderfga/claw-orchestrator/tree/main/skills" language: TypeScript stars: 553 forks: 90 install: "npx degit https://github.com/Enderfga/claw-orchestrator/tree/main/skills ~/.claude/skills/skills" installs_to: ~/.claude/skills/skills source_path: skills/SKILL.md collection_size: 3 category_size: 2451 collection_url: "https://dirskills.com/collections/Enderfga/claw-orchestrator" added: 2026-08-25T05:15:10.635Z last_synced: 2026-08-25T05:15:10.635Z canonical_url: "https://dirskills.com/skills/claw-orchestrator" --- # Claw Orchestrator Claw Orchestrator manages persistent coding sessions across Claude Code, Codex, Antigravity, Grok Build, and OpenCode. Use it to start, send to, stop, and coordinate multi-engine agent runs, including council, review, and planning workflows. **Install:** ```bash npx degit https://github.com/Enderfga/claw-orchestrator/tree/main/skills ~/.claude/skills/skills ``` ## README # 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 | 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 ```javascript // 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 | Parameter | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------- | | `engine` | `claude` (default), `codex`, `agy`, `cursor`, `opencode` | | `model` | Model name or alias (`fable`, `opus`, `sonnet`, `haiku`, `gpt-5.5`, `agy-pro`, `composer-2`) | | `permissionMode` | `acceptEdits`, `auto`, `plan`, `bypassPermissions`, `manual`, `dontAsk` (`default` = legacy alias for `manual`) | | `effort` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` (`xhigh` is Opus 4.7-only, between `high` and `max`) | | `maxBudgetUsd` | Cost limit in USD | | `allowedTools` | List of allowed tool names | ### CLI 2.1.111 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). | ### CLI 2.1.121 options | Parameter | Description | | --------------------- | --------------------------------------------------------------------------------------------- | | `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` 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. ```javascript // 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](references/council.md) ## Cross-Session Messaging Sessions can communicate. Idle sessions receive immediately; busy sessions queue. ```javascript 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.) ```javascript 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. ```javascript 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](references/autoloop.md). ## Tools Overview | Category | Tools | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Session Lifecycle | `session_start`, `session_send`, `session_stop`, `session_list`, `sessions_overview` | | Session Ops | `coding_session_status`, `session_grep`, `session_compact`, `session_update_tools`, `session_switch_model` | | 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_threads` | | 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` | `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](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](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//`, 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](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 `. 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](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 ] [--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](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`)