convez.ai
MCP ServerDevOps & InfraestruturaAvançado
wccjitou-lgtm

MoA Orchestrator

wccjitou-lgtm/moa-orchestrator

Agentes IA multi-worker para código com patches revisáveis e controle humano

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor 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-orchestrator

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

    {
      "goal": "Add a small module, tests, and documentation",
      "scope": "project",
      "context": {
        "repoRoot": "C:\\path\\to\\repo",
        "contextFiles": ["src/index.js", "test/index.test.js"]
      }
    }
    
  2. Run the saved plan without another Claude call:

    {
      "planId": "plan-...",
      "autoApply": false
    }
    
  3. Poll the run:

    { "runId": "run-..." }
    
  4. 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:

  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

ToolPurpose
moa.healthCheck Node, Git, Codex CLI, and safe configuration summary.
moa.planCall Claude once for project or node planning and return JSON with usage.
moa.implementStart one async Codex worker and return a taskId immediately.
moa.runStart an async dependency-aware multi-node run.
moa.taskStatusPoll an implement task or a whole run by taskId or runId.
moa.applyPreview, apply, or roll back patches with explicit confirmation.
moa.listRunsList recent run archives.
moa.retryNodeRetry one failed node from an archived run without replanning.
moa.cleanupRemove orphaned MoA temp worktrees and message directories.

Documentation

Configuration

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

VariableDefaultDescription
MOA_CLAUDE_API_KEY_ENVANTHROPIC_API_KEYName of the environment variable that stores the Claude key.
MOA_CLAUDE_BASE_URL / ANTHROPIC_BASE_URLhttps://api.anthropic.comAnthropic or compatible API base URL.
MOA_CLAUDE_MODELclaude-opus-4-8Claude model name.
MOA_CLAUDE_MAX_TOKENS16384Maximum output tokens for planner calls.
MOA_CODEX_COMMANDcodexCodex CLI command.
MOA_CODEX_MODELunsetOptional Codex model override.
MOA_CODEX_ISO_HOME.moa/codex-homeIsolated Codex home used by workers.
MOA_MAX_CLAUDE_CALLS_PER_RUN2Claude call budget per run.
MOA_MAX_CLAUDE_TOKENS_PER_RUN200000Claude token budget per run.
MOA_MAX_PARALLEL_WORKERS2Maximum concurrent Codex workers.
MOA_PLANNER_TIMEOUT_MS600000Planner timeout.
MOA_WORKER_TIMEOUT_MS600000Worker timeout.
MOA_MAX_INLINE_DIFF_BYTES200000Inline diff response limit.
MOA_MAX_PLAN_CONTEXT_BYTES60000Planner repository context byte limit.
MOA_RUNS_DIR.moa/runsRun archive directory.
MOA_TASKS_DIR.moa/tasksAsync 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", "<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.

Ver o original no GitHub

Bom para

Relacionados