claw-orchestrator

Files (21)

• SKILL.md
• SKILL.md · claw-orchestrator/
• acp.md · references/
• autoloop.md · references/
• claude-cli-tracking.md · references/
• cli.md · references/
• council.md · references/
• dashboard.md · references/
• getting-started.md · references/
• inbox.md · references/
• mcp.md · references/
• multi-engine.md · references/
• observability.md · references/
• openai-compat.md · references/
• sessions.md · references/
• tools.md · references/
• ultra.md · references/
• ultraapp.md · references/
• verification.md · references/
• workflow.md · references/
• SKILL.md · ultraapp/

SKILL.md (first lines)

# 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, any Agent Client Protocol agent, 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; the thread is resumed on each send                             |
| `codex-app` | `codex app-server`           | Persistent subprocess | Codex `/goal`, plus interrupt / steer / fork / rollback of turns                   |
| `agy`       | `agy -p`                     | Per-message spawn     | Google Antigravity; reported token usage, conversation resumed by id               |
| `grok`      | `grok -p`                    | Per-message spawn     | xAI Grok Build; engine-reported cost, resumable session                            |
| `opencode`  | `opencode run`               | Per-message spawn     | Provider-agnostic (`provider/model`)                                               |
| `acp`       | the agent's own command      | Persistent subprocess | Any Agent Client Protocol agent, named by `acpAgent` (presets: `kimi-code`, `dsh`) |
| `custom`    | yours (`CustomEngineConfig`) | Either (`persistent`) | Any other coding CLI, described by a config or a bundled preset                    |

## 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-5',
});
session_start({ name: 'kimi-task', cwd: '/path/to/project', engine: 'acp', acpAgent: 'kimi-code' });

// 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`, `codex-app`, `agy`, `grok`, `opencode`, `acp`, `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, enforced by the runtime on every engine                                                                                                                                                                                                            |
| `allowedTools`    | List of allowed tool names                                                                                                                                                                                                                                            |
| `sandboxMode`     | `read-only`, `workspace-write`, `danger-full-access`. Codex applies all three; claude, agy, grok and opencode enforce `read-only` through their own plan/read-only modes; a custom engine must map it through `permissionModes` or refuses to start; `acp` refuses it |
| `acpAgent`        | With `engine: 'acp'`: a bundled preset id (`clawo engines`), or an inline `{ name, command, args, env }` from a local caller                                                                                                                                          |
| `customEngine`    | With `engine: 'custom'`: a bundled preset id, or an inline `CustomEngineConfig` from a local caller                                                                                                                                                                   |
| `resumeSessionId` | Resume an earlier conversation by the engine's own id (session, thread or conversation id)                                                                                                                                                                            |

### 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.

```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.)

From Enderfga/claw-orchestrator, MIT.

More from Enderfga/claw-orchestrator