Agent Orchestrator

Local MCP orchestrator for managing Codex, Claude, and Cursor worker runs through a persistent daemon, with a daemon-owned orchestration_run engine for multi-step workflows.

What It Does

Agent Orchestrator lets a supervising MCP client start local worker runs, watch progress, send follow-ups, cancel work, and inspect durable run results. The stdio MCP server stays small; a local daemon owns worker subprocesses, timeouts, notifications, run metadata, logs, and session reuse.

The 0.3.0 release (issue #63) adds the orchestration_run engine — a daemon-managed state machine that drives short-lived orchestrator / reviewer / compactor turns through a typed action protocol, with persistent state, lifecycle pub/sub, an MCP push channel, an IPC long-poll surface, a CLI (orchestrate ...), and an opt-in read-only HTTP+SSE transport. See docs/orchestration.md.

It is meant for developers who already use local agent CLIs and want a safer control plane for delegating work.

What It Does Not Do

• It does not install Codex, Claude Code, or Cursor credentials.
• It does not host a remote service or send prompts to an orchestrator-owned cloud.
• It does not isolate filesystems, create worktrees, or prevent two workers from editing the same file.
• It does not make missing CLI auth disappear; diagnostics report what the host can actually run.

Project Status

• Maturity: usable, published, and still evolving before a broad public launch.
• Runtime: Node.js 22 or newer.
• Platforms: Linux and macOS run the full CI verification matrix on Node 22 and 24. Windows runs build, focused Windows tests, and packed CLI smoke tests on Node 22 and 24.
• Worker backends: Codex, Claude, Cursor.
• Orchestration engine: Codex + Claude in v1 (per decision D15); OpenCode and Cursor are not orchestration-turn backends in this release.
• Known limitation: Windows orchestration of Claude workers requires Git Bash because Claude Code uses Bash for its Bash tool.

Install

Use the published package directly from any MCP client:

npx -y @ralphkrauss/agent-orchestrator@latest

For a local checkout:

pnpm install --frozen-lockfile
pnpm build
node dist/cli.js doctor

Five-Minute Quickstart

Run diagnostics first. This makes no model calls.

npx -y @ralphkrauss/agent-orchestrator@latest doctor
npx -y @ralphkrauss/agent-orchestrator@latest doctor --json

Expected shape:

Agent Orchestrator diagnostics
Frontend version: 0.3.0
Platform: darwin
Node: v24.15.0
Backends:
- codex: auth_unknown
- claude: auth_unknown
- cursor: auth_unknown

missing means the worker binary or SDK is not available. auth_unknown means the backend looks runnable, but the package cannot prove auth without asking that backend to make a model call.

Add the MCP server to one client. Persistent MCP client entries should pin a concrete package version so restarts use the same MCP surface; the examples below use 0.3.0.

{
  "mcpServers": {
    "agent-orchestrator": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ralphkrauss/[email protected]"]
    }
  }
}

Then use the MCP tools from that client:

get_backend_status({})

Create a profile. Choose a model id that your local backend accepts. The example below uses worker_posture: "restricted" together with codex_network: "isolated" to keep the worker on the closed-network, --ignore-user-config envelope. Omit both fields (or use worker_posture: "trusted", the default since #58) for backend-native parity with a manual codex exec run — see docs/reference.md for the two-axis posture × codex_network argv table.

upsert_worker_profile({
  "profile": "codex-local",
  "backend": "codex",
  "model": "<codex-model-id>",
  "worker_posture": "restricted",
  "codex_network": "isolated",
  "description": "Local Codex worker with closed network egress (restricted posture)"
})

Start one run:

start_worker({
  "profile": "codex-local",
  "prompt": "Run pwd and summarize the repository in one sentence.",
  "cwd": "/path/to/workspace"
})

Expected result:

{ "ok": true, "run_id": "01..." }

Inspect it:

get_worker_progress({ "run_id": "01..." })
get_worker_result({ "run_id": "01..." })

To also wake an OpenClaw Telegram topic when the worker finishes:

start_worker({
  "profile": "codex-local",
  "prompt": "...",
  "cwd": "/path/to/workspace",
  "notification_subscriptions": [{
    "client_subscription_id": "telegram-topic-42",
    "target": {
      "type": "openclaw_agent_hook",
      "base_url": "https://openclaw.internal",
      "agent_id": "chat-1",
      "session_key": "telegram:topic:42",
      "channel": "telegram",
      "to": "telegram:-1001234567890:topic:42"
    }
  }]
})

See docs/first-run.md for a complete first-run guide, common failures, daemon restart commands, and no-model-call paths.

MCP-Only Orchestration Flow

Agents can operate workflow-driven orchestration runs without shelling out to the CLI. A typical MCP loop is:

get_orchestration_capabilities({})
list_orchestration_workflows({ "cwd": "/path/to/workspace" })
start_orchestration_run({
  "workflow": "implement-plan",
  "goal": "implement the new auth flow per the plan",
  "cwd": "/path/to/workspace",
  "request_id": "client-generated-retry-key"
})
subscribe_orchestration_events({
  "orchestration_run_ids": ["01..."],
  "wait_seconds": 30,
  "limit": 20
})
get_orchestration_summary({ "orchestration_run_id": "01..." })
list_pending_orchestration_inputs({})
submit_orchestration_human_input({
  "orchestration_run_id": "01...",
  "input_request_id": "q...",
  "text": "Proceed with the narrower implementation.",
  "request_id": "client-generated-answer-key"
})
wait_for_any_orchestration_run({
  "orchestration_run_ids": ["01..."],
  "wait_seconds": 60
})
list_orchestration_notifications({
  "orchestration_run_ids": ["01..."],
  "include_acked": false
})
ack_orchestration_notification({ "notification_id": "n..." })
get_orchestration_summary({ "orchestration_run_id": "01..." })

Use start_orchestration_run for workflow-managed multi-step work. Use start_worker for one ad hoc worker prompt. MCP push notifications on notifications/orchestration/changed are advisory hints; agents should re-read summaries, artifacts, events, or durable notifications before acting. Agents should ack durable orchestration notifications only after acting on or dismissing them, and keep separate cursors for lifecycle events (after_event_id) and durable notifications (since_notification_id / after_notification_id). For operator control, agents can also call pause_orchestration_run, resume_orchestration_run, or cancel_orchestration_run with an explicit reason.

MCP Client Config

Persistent MCP client entries should pin a concrete package version. Use @latest for one-off diagnostics, and update pinned client config versions when intentionally upgrading.

Claude Code .mcp.json:

{
  "mcpServers": {
    "agent-orchestrator": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@ralphkrauss/[email protected]"]
    }
  }
}

Codex .codex/config.toml:

[mcp_servers.agent-orchestrator]
command = "npx"
args = ["-y", "@ralphkrauss/[email protected]"]

Cursor .cursor/mcp.json:

{
  "mcpServers": {
    "agent-orchestrator": {
      "command": "npx",
      "args": ["-y", "@ralphkrauss/[email protected]"]
    }
  }
}

Supported Backends

| Backend | How it authenticates | Notes | |---|---|---| | Codex | Codex CLI auth or OPENAI_API_KEY / CODEX_API_KEY in the daemon environment | codex_network controls whether worker network egress is isolated, workspace-enabled, or inherited from user config. Orchestration-turn backend in v1. | | Claude | Claude CLI auth, ANTHROPIC_API_KEY, or registered Claude accounts | Account registry supports config_dir and api_env modes with rotation on rate-limit. Orchestration-turn backend in v1. | | Cursor | CURSOR_API_KEY in the daemon environment or daemon-managed secrets file | Uses @cursor/sdk as an optional dependency and runs SDK work in-process. Worker-run only in v1; not an orchestration-turn backend. |

Security Model

This is a trusted-local tool. Worker processes run as the current OS user, inherit the daemon environment, and can access the credentials that the selected backend CLI can access.

• Do not expose the daemon IPC endpoint to untrusted users.
• Do not paste API keys into prompts or MCP tool arguments.
• Prompts, stdout, stderr, events, and results are written to the local run store.
• Default run store: ~/.agent-orchestrator.
• Secret-bearing development MCP configs use the repo-local secret bridge; real tokens must stay outside repo files.

Read SECURITY.md before using this with sensitive repositories.

Reference Docs

• First successful run
• Orchestration engine overview
• Workflow JSON schema and examples
• Orchestration HTTP+SSE transport
• MCP tool guide
• Orchestration internals (contributors)
• Architecture, daemon lifecycle, run store, and MCP tools
• Repository map
• Daemon auth setup
• Codex backend and codex_network
• Claude multi-account setup
• Cursor backend
• MCP tooling for this repository
• Roadmap
• Publishing

Contributing

See CONTRIBUTING.md. The release-quality local gate is:

pnpm install --frozen-lockfile
pnpm verify

pnpm verify builds, runs tests, checks publish readiness, audits production dependencies, resolves the npm dist-tag, and runs an npm pack dry run.