Moa Orchestrator

MoA Orchestrator

MoA Orchestrator is a local MCP server for agentic software engineering. It coordinates a cost-controlled Claude Planner and isolated Codex implementation workers, then returns reviewable patches instead of directly changing your main workspace.

[中文](docs/README.zh-CN.md) · [English](README.md) · [Français](docs/README.fr.md) · [Deutsch](docs/README.de.md)

[Quick Start](#quick-start) · [How It Works](#how-it-works) · [MCP Tools](#mcp-tools) · [Documentation](#documentation) · [Configuration](#configuration) · [Troubleshooting](#troubleshooting) · [Contributing](#contributing)

---

Why MoA?

LLM agents are powerful, but coordinating them safely is hard. MoA turns multi-agent coding into a local, auditable workflow:

• Claude plans only through the Anthropic Messages API.
• Codex implements only inside isolated temporary git worktrees.
• Patches are the boundary: workers return unified diffs and patch references.
• Humans stay in control: only moa.apply with confirm:true can modify the main workspace.
• Runs are observable: task status, run manifests, worker logs, patches, and rollback records are stored under .moa/.

Quick Start

Requirements

• Node.js 20+
• Git
• Codex CLI on PATH
• Claude credentials when using moa.plan or moa.run
• Codex Desktop or another MCP client that can call stdio MCP servers

Check the local tools first:

node --version
git --version
cmd /c codex --version

Clone And Install

git clone https://github.com/wccjitou-lgtm/moa-orchestrator.git
cd moa-orchestrator
cmd /c npm install
cmd /c npm test

Configure Claude

MoA reads secrets only from environment variables. The default Claude key variable is ANTHROPIC_API_KEY.

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "YOUR_ANTHROPIC_KEY", "User")

For Anthropic-compatible relays:

[Environment]::SetEnvironmentVariable("MOA_CLAUDE_API_KEY_ENV", "ANTHROPIC_AUTH_TOKEN", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "YOUR_RELAY_TOKEN", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://your-relay.example", "User")

Restart Codex Desktop after setting user-level environment variables. Desktop apps usually do not inherit variables from an already-open terminal.

Register With Codex Desktop

Use the absolute path to the cloned repository:

cmd /c codex mcp add moa -- node "C:\path\to\moa-orchestrator\src\server.js"

Verify:

cmd /c codex mcp get moa
cmd /c npm test -- test/server.test.js

Restart Codex Desktop, then call moa.health.

Expected moa.health shape:

{
  "ok": true,
  "dependencies": {
    "node": { "ok": true },
    "git": { "ok": true },
    "codex": { "ok": true }
  },
  "config": {
    "claudeApiKeyPresent": true
  }
}

Minimal Flow

1. Ask MoA to plan:

``json { "goal": "Add a small module, tests, and documentation", "scope": "project", "context": { "repoRoot": "C:\\path\\to\\repo", "contextFiles": ["src/index.js", "test/index.test.js"] } } ``

1. Run the saved plan without another Claude call:

``json { "planId": "plan-...", "autoApply": false } ``

1. Poll the run:

``json { "runId": "run-..." } ``

1. Preview, then apply only after review:

``json { "repoRoot": "C:\\path\\to\\repo", "runId": "run-...", "confirm": false } ``

``json { "repoRoot": "C:\\path\\to\\repo", "runId": "run-...", "confirm": true } ``

Codex Desktop Deployment Checklist

Use this checklist when setting MoA up on a new machine:

1. git clone this repository and run cmd /c npm install.
2. Run cmd /c npm test; all tests should pass before registering the MCP server.
3. Run cmd /c codex --version; if this fails, install or repair the Codex CLI first.
4. Set ANTHROPIC_API_KEY or configure MOA_CLAUDE_API_KEY_ENV for your relay.
5. Restart Codex Desktop so it inherits the environment variables.
6. Register MoA with cmd /c codex mcp add moa -- node "ABSOLUTE_PATH\src\server.js".
7. Run cmd /c codex mcp get moa and confirm it is enabled with stdio transport.
8. In Codex Desktop, call moa.health.
9. Only after health is green, try moa.plan with a small goal.

How It Works

User / Codex Desktop
        |
        | MCP tool call
        v
MCP Server: moa
        |
        +--> Claude Planner
        |      - project or node planning
        |      - bounded repository context
        |      - JSON output only
        |
        +--> Codex Workers
        |      - codex exec
        |      - isolated CODEX_HOME
        |      - temporary detached git worktree
        |      - unified diff output
        |
        +--> Patch Gate
               - preview
               - git apply --3way
               - rollbackRef

MoA deliberately separates responsibilities:

• Planning: Claude decomposes goals into nodes, dependencies, routes, interfaces, and acceptance checks.
• Implementation: Codex workers execute node contracts in isolated worktrees.
• Archiving: plans, tasks, logs, diffs, and run manifests are written to .moa/.
• Application: moa.apply is the only path that changes the main workspace.

MCP Tools

| Tool | Purpose | | --- | --- | | moa.health | Check Node, Git, Codex CLI, and safe configuration summary. | | moa.plan | Call Claude once for project or node planning and return JSON with usage. | | moa.implement | Start one async Codex worker and return a taskId immediately. | | moa.run | Start an async dependency-aware multi-node run. | | moa.taskStatus | Poll an implement task or a whole run by taskId or runId. | | moa.apply | Preview, apply, or roll back patches with explicit confirmation. | | moa.listRuns | List recent run archives. | | moa.retryNode | Retry one failed node from an archived run without replanning. | | moa.cleanup | Remove orphaned MoA temp worktrees and message directories. |

Documentation

• [Controller orchestration protocol](ORCHESTRATION.md)
• [Technical specification](SPEC.md)
• [Project introduction page](docs/project-introduction.html)
• [Execution trace introduction page](docs/project-introduction-trace.html)
• [Chinese README](docs/README.zh-CN.md)
• [French README](docs/README.fr.md)
• [German README](docs/README.de.md)

Configuration

MoA can be configured with environment variables or a local config.json. Do not commit config.json.

| Variable | Default | Description | | --- | --- | --- | | MOA_CLAUDE_API_KEY_ENV | ANTHROPIC_API_KEY | Name of the environment variable that stores the Claude key. | | MOA_CLAUDE_BASE_URL / ANTHROPIC_BASE_URL | https://api.anthropic.com | Anthropic or compatible API base URL. | | MOA_CLAUDE_MODEL | claude-opus-4-8 | Claude model name. | | MOA_CLAUDE_MAX_TOKENS | 16384 | Maximum output tokens for planner calls. | | MOA_CODEX_COMMAND | codex | Codex CLI command. | | MOA_CODEX_MODEL | unset | Optional Codex model override. | | MOA_CODEX_ISO_HOME | .moa/codex-home | Isolated Codex home used by workers. | | MOA_MAX_CLAUDE_CALLS_PER_RUN | 2 | Claude call budget per run. | | MOA_MAX_CLAUDE_TOKENS_PER_RUN | 200000 | Claude token budget per run. | | MOA_MAX_PARALLEL_WORKERS | 2 | Maximum concurrent Codex workers. | | MOA_PLANNER_TIMEOUT_MS | 600000 | Planner timeout. | | MOA_WORKER_TIMEOUT_MS | 600000 | Worker timeout. | | MOA_MAX_INLINE_DIFF_BYTES | 200000 | Inline diff response limit. | | MOA_MAX_PLAN_CONTEXT_BYTES | 60000 | Planner repository context byte limit. | | MOA_RUNS_DIR | .moa/runs | Run archive directory. | | MOA_TASKS_DIR | .moa/tasks | Async task state directory. |

Example:

{
  "claude": {
    "apiKeyEnv": "ANTHROPIC_API_KEY",
    "baseUrl": "https://api.anthropic.com",
    "model": "claude-opus-4-8",
    "maxTokens": 16384
  },
  "limits": {
    "maxClaudeCallsPerRun": 2,
    "maxParallelWorkers": 2,
    "workerTimeoutMs": 600000
  }
}

Safety Model

• Claude is never invoked through the Claude CLI.
• Claude is never used inside implementation loops.
• Worker prompts are passed through stdin.
• Workers run in temporary detached git worktrees under os.tmpdir().
• Workers use an isolated CODEX_HOME.
• Windows .cmd wrappers are spawned with shell:true; git.exe uses argument arrays.
• Main workspace writes require moa.apply and confirm:true.
• Rollback deletes only files added by the recorded apply operation and checks out only touched tracked files.

Troubleshooting

moa.plan reports missing Claude credentials

Set the environment variable named by MOA_CLAUDE_API_KEY_ENV. By default:

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "", "User")

Make sure Codex Desktop was launched from an environment that contains that variable.

Claude planning times out

Reduce contextFiles, lower MOA_MAX_PLAN_CONTEXT_BYTES, split the goal, or increase MOA_PLANNER_TIMEOUT_MS. Some MCP clients may still enforce their own shorter tool-call timeout.

Codex worker fails because of global Codex state

MoA workers use an isolated CODEX_HOME and avoid copying global skills. Inspect the node log under .moa/runs//.

A worker stays running too long

Check:

{ "taskId": "implement-..." }

moa.taskStatus reports elapsedMs, lastHeartbeat, and pid. Hard timeouts mark the task failed and clean up the worktree.

Patch conflicts during apply

Run preview first:

{ "repoRoot": "C:\\path\\to\\repo", "runId": "run-...", "confirm": false }

If conflicts appear, inspect the patch archive and regenerate or resolve manually.

Worktree leftovers

Use:

{}

with moa.cleanup. It only scans MoA temp prefixes such as moawt-* and moacodexmsg-*.

Development

Run all tests:

cmd /c npm test

Run milestone subsets:

cmd /c npm run test:m0
cmd /c npm run test:m1
cmd /c npm run test:m2
cmd /c npm run test:m3
cmd /c npm run test:m4

Contributing

Contributions are welcome. Good first areas include:

• Planner prompt and repository context selection
• Worker lifecycle and cross-platform hardening
• Run archive visualization
• More MCP client examples
• Documentation and translated guides
• Test coverage for edge cases

Read [CONTRIBUTING.md](CONTRIBUTING.md), [CODEOFCONDUCT.md](CODEOFCONDUCT.md), and [SECURITY.md](SECURITY.md) before opening a pull request.

License

MIT. See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wccjitou-lgtm
• Source: wccjitou-lgtm/moa-orchestrator
• License: MIT

Install and usage instructions live in the source repository linked above.