# Claw Orchestrator

> Manages persistent coding sessions across multiple AI coding engines including Claude Code, Codex, Antigravity, Cursor, and OpenCode, with support for multi-agent councils, cross-session messaging, deep planning, parallel code review, and autonomous workspace iteration.

- Skill: `gabrielmoreira/claw-orchestrator` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds add gabrielmoreira/claw-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/claw-orchestrator/raw
- Safety review: CAUTION (external: skill-scanner FAIL, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, DevOps & Infra, Deployment & Release, Dev Tooling
- Tags: Antigravity, Claude Code, Codex, Cursor, Mcp Server, Multi Agent, Opencode, Session Management
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/gabrielmoreira/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, Cursor Agent, OpenCode, and custom CLIs into headless agentic engines with 69 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 |
| `cursor` | `agent -p` | Per-message spawn | One-shot execution |
| `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: "cursor-task", cwd: "/path/to/project", engine: "cursor" })
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)

## 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
- **Cursor**: `agent login` or `CURSOR_API_KEY`
- **OpenCode**: `opencode auth login` (provider-agnostic; use `provider/model` form for `model`)