Enderfga/claw-orchestrator

What is Claw Orchestrator?

Claw Orchestrator is a Node‑JS runtime that lets you run coding‑assistant agents (Claude Code, Codex, Antigravity, Grok Build, OpenCode, or any custom CLI) behind a single API. It treats the agents as persistent sessions and adds a verification layer that checks the work themselves – the runtime runs the tests, HTTP probes, file diffs, etc., and records the result on disk. A run is only marked verified when the runtime’s own checks pass, so you never have to trust the agent’s “All tests pass” claim.

---

Core ideas

Idea	What it gives you
Acceptance contracts	Declare the checks (e.g., npm test, HTTP request, screenshot) that the runtime will execute after the agent finishes. The run ends verified, refuted or unverified – never “the agent said so”.
Multi‑engine runtime	One CLI / HTTP API that can talk to Claude Code, Codex, Antigravity, Grok Build, OpenCode, or any custom tool. You can fan‑out a single prompt to several engines at once.
Session hand‑off	Move a live conversation from one engine to another (e.g., from a costly Claude model to a cheaper Codex) without losing context or workspace state.
Durable workflow kernel	Every state transition is checkpointed to disk. If the process crashes you can resume, retry, timeout, or cancel runs without losing work.
Run ledger & budget caps	A JSONL ledger records tokens, cost, duration, and engine per turn. You can set a maxBudgetUsd so the runtime enforces a hard spend limit across all engines.
Embedded dashboard	A web UI (http://127.0.0.1:18796/dash) shows live event streams, run history, and controls for sessions, councils, autoloops, etc.
OpenAI‑compatible proxy	Exposes a /v1/chat/completions endpoint that forwards OpenAI‑style requests to the appropriate persistent session, letting any OpenAI client talk to the orchestrator unchanged.

---

Main features (at a glance)

• Persistent sessions – keep the agent’s context alive across many messages.
• Multi‑engine fan‑out – run the same task on N models in parallel, optionally synthesize a single answer.
• Council & autoloop – built‑in primitives for three‑agent loops (Planner → Coder → Reviewer) and consensus voting.
• Ultra‑code / ultra‑app – higher‑level constructs that let Claude orchestrate sub‑agents or generate a full web app from a short interview.
• Verification plane – contracts are executed by the runtime; evidence (logs, diffs, screenshots) is stored on disk.
• Observability – per‑turn ledger, cost caps, and a dashboard for real‑time monitoring.
• Integrations – CLI, MCP plugin (for editors like Zed, JetBrains, Cursor, etc.), ACP agent (standard Agent Client Protocol), and a TypeScript SDK.

---

Quick start (CLI)

# Install globally
npm install -g @enderfga/claw-orchestrator

# Start the local server + dashboard
clawo serve   # → http://127.0.0.1:18796/dash

# Simple solve request using Claude Code
clawo solve "Fix the failing tests" \
  --engine claude \
  --check "npm test" \
  --wait

# Run the same prompt on three engines and synthesize a answer
clawo fanout "How would you speed up this test suite?" \
  --engines claude,codex,grok \
  --synthesize \
  --wait

# List recent runs (shows cost, tokens, verdict, etc.)
clawo runs --since 1h

The server writes an access token to ~/.openclaw/server-token; the CLI reads it automatically.

---

Example workflow (verification in action)

1. Declare a contract – --check "npm test" tells the runtime to run the project’s test suite after the agent finishes.
2. Agent works – Claude Code (or another engine) edits price.js trying to make the tests pass.
3. Runtime verifies – It executes npm test itself. If the test still fails, the run is marked refuted; if it passes, verified.
4. Evidence stored – All command output, changed files, and diff snapshots are saved on disk for later audit.

---

How to embed in your own code (TypeScript SDK)

import { SessionManager } from '@enderfga/claw-orchestrator';

const manager = new SessionManager();
await manager.startSession({
  name: 'fix-tests',
  engine: 'claude',
  cwd: '/my/project'
});

const result = await manager.sendMessage('fix-tests', 'Fix the failing tests');
console.log(result.verdict); // 'verified' | 'refuted' | 'unverified'

The SDK talks to the local clawo-mcp server, so you get the same verification guarantees as the CLI.

---

When would you use it?

• CI‑style safety for AI‑generated code – let the model propose changes but let the runtime enforce that the project’s own test suite (or any custom contract) actually passes.
• Cost‑controlled multi‑model experimentation – compare several vendors on the same task, see which one gives the cheapest correct answer, and enforce a budget.
• Complex autonomous workflows – build self‑iterating loops (Planner‑Coder‑Reviewer) or councils that converge on a solution without human intervention.
• Tool‑rich editor integrations – plug the runtime into Zed, JetBrains, VS Code, etc., and get the same verification guarantees inside the IDE.

---

License & contribution

• License: MIT
• Contributing: Follow the guidelines in CONTRIBUTING.md; run npm run build && npm run lint && npm run format:check && npm run test before opening a PR.

---

Bottom line: Claw Orchestrator gives you a single, durable runtime for running multiple AI coding agents, with an independent verification step that makes the results trustworthy and auditable.