MoA Orchestrator
wccjitou-lgtm/moa-orchestrator
Agentes IA multi-worker para código com patches revisáveis e controle humano
Ver no GitHubServidor MCP local que orquestra agentes Claude para engenharia de software segura e auditável. Coordena um planejador Claude com custo controlado e workers Codex isolados, retornando patches revisáveis em vez de modificar diretamente o workspace.
Instalação
npx convez-ai wccjitou-lgtm/moa-orchestrator1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Planejamento e execução de tarefas de desenvolvimento controladas por IA
- Implementação segura de mudanças de código com patches auditáveis
- Automação de engenharia de software com rollback rastreável
Veredito

Ferramenta robusta para times que precisam de automação de código com auditoria e controle explícito. Requer familiaridade com MCP, Git e APIs Claude, mas oferece garantias de segurança e rastreabilidade superiores para orquestração multi-agent em produção.
README
A tradução para o português deste README ainda está na fila.
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.
中文 · English · Français · Deutsch
Quick Start · How It Works · MCP Tools · Documentation · Configuration · Troubleshooting · 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.applywithconfirm:truecan 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.planormoa.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
-
Ask MoA to plan:
{ "goal": "Add a small module, tests, and documentation", "scope": "project", "context": { "repoRoot": "C:\\path\\to\\repo", "contextFiles": ["src/index.js", "test/index.test.js"] } } -
Run the saved plan without another Claude call:
{ "planId": "plan-...", "autoApply": false } -
Poll the run:
{ "runId": "run-..." } -
Preview, then apply only after review:
{ "repoRoot": "C:\\path\\to\\repo", "runId": "run-...", "confirm": false }{ "repoRoot": "C:\\path\\to\\repo", "runId": "run-...", "confirm": true }
Codex Desktop Deployment Checklist
Use this checklist when setting MoA up on a new machine:
git clonethis repository and runcmd /c npm install.- Run
cmd /c npm test; all tests should pass before registering the MCP server. - Run
cmd /c codex --version; if this fails, install or repair the Codex CLI first. - Set
ANTHROPIC_API_KEYor configureMOA_CLAUDE_API_KEY_ENVfor your relay. - Restart Codex Desktop so it inherits the environment variables.
- Register MoA with
cmd /c codex mcp add moa -- node "ABSOLUTE_PATH\src\server.js". - Run
cmd /c codex mcp get moaand confirm it is enabled with stdio transport. - In Codex Desktop, call
moa.health. - Only after health is green, try
moa.planwith 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.applyis 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
- Technical specification
- Project introduction page
- Execution trace introduction page
- Chinese README
- French README
- German README
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
.cmdwrappers are spawned withshell:true;git.exeuses argument arrays. - Main workspace writes require
moa.applyandconfirm: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", "<your-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/<runId>/.
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, CODE_OF_CONDUCT.md, and SECURITY.md before opening a pull request.
License
MIT. See LICENSE.