codex-orchestrator MCP server
Commit Nov 10, 2026Delegates coding tasks to OpenAI Codex and runs an autonomous loop of implementation, verification, and review until project goals are met.
Also known as Solarthis/codex-massa
- Stars
- 0
- Tools
- 9
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 10, 2026
- License
- MIT
What is codex-orchestrator MCP?
codex-orchestrator delegates coding tasks to OpenAI Codex and runs an autonomous loop of implementation, verification, and review until project goals are met. It exposes 9 tools, such as project_dir, goal_file, max_iterations.
Summary generated from the project's README
About codex-orchestrator MCP server
Automating complex coding implementations through an autonomous loop is what codex-massa enables for developers using Claude Code or other MCP clients. By delegating implementation work to OpenAI Codex, this local orchestrator manages a continuous cycle of task execution, verification, and review. It continues this process until a specific project goal is achieved or a safety limit is reached.
The system provides five specialized tools including start_project_loop, codex_task, review_current_state, get_loop_status, and stop_loop. Users can configure the environment using the CODEX_ORCHESTRATOR_MODE variable to switch between real execution, legacy mcp-server modes, or a mock mode for testing without network access. For real-world tasks, the OpenAI Codex CLI must be installed and authenticated on the local machine.
Integration is streamlined through a dedicated slash command for Claude Code that guides users through goal clarification and checklist creation. The orchestrator includes safety guards to monitor outgoing prompts and observed diffs, ensuring that autonomous actions remain within defined boundaries like the workspace-write sandbox.
What you can do with it
- 1Autonomous feature implementationStart a background loop that implements a project goal by following a machine-checkable checklist.
- 2Verify code completionCompare current code changes against a goal checklist using git diff and verification commands.
- 3Test the orchestration logicRun the entire implementation loop using mock data to prove the workflow without making real API calls.
- 4Single task delegationSend a specific coding prompt directly to Codex to get an immediate implementation response.
Written from the project's README. Every use case is checked against a quote from it.
codex-orchestrator MCP tools 9
Detected from the READMEproject_dirgoal_filemax_iterationsverification_commandssandboxapproval_policypromptthread_idrun_id
Configuration
CODEX_ORCHESTRATOR_MAX_RUNTIME_MSCODEX_ORCHESTRATOR_MODE
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesolarthis/codex-massa is public and reachablegithub.com/solarthis/codex-massa ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-10github.com/solarthis/codex-massa ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcodex-orchestrator
A local MCP-based orchestrator that lets Claude Code (or any MCP client) delegate implementation work to OpenAI Codex, review Codex's output, run verification, send targeted follow-ups, and loop until a project goal passes or a safety limit is hit.
It runs two ways from the same code:
- as an MCP server (official
@modelcontextprotocol/sdk) exposing 5 tools, and - as a thin CLI that drives the identical loop.
It ships with a dry-run / mock mode that proves the whole loop end-to-end (checklist → task → verify → review → follow-up → done) with no real Codex call and no network.
It also ships a ready-made /massa slash command for Claude Code
(commands/massa.md) that drives the whole flow: it
clarifies the goal with you, writes PROJECT_GOAL.md, starts the loop, and
reports progress. See The /massa command.
Contents
- Architecture
- Requirements
- Install & build
- Quick start: the dry-run proof
- The 5 MCP tools
- Register in Claude Code (exact config)
- The /massa command for Claude Code
- Worker modes
- Installing & configuring the real Codex CLI
- CLI usage
- The autonomous loop
- Safety guards & limits
- State & logs layout
- Worked end-to-end example
- Codex CLI compatibility
- Troubleshooting
Architecture
- Runtime: TypeScript / Node (ESM), built with
tsc. Tests use the built-innode:testrunner — no extra test dependency. - Integration path:
codex exec --jsonis the default worker transport (codex-cli 0.155+ removedcodex mcp-server, which remains available via--mode mcp-serverfor older CLIs). Both sit behind oneCodexClientinterface alongside a mock impl. - Dependencies (pinned):
@modelcontextprotocol/sdk(mandated SDK) andzod(the SDK's tool-schema API). Dev:typescript,@types/node. Nothing else.
Modules (each in its own file under src/)
| File | Responsibility |
|---|---|
codex-client.ts |
Codex worker behind one interface: MockCodexClient, McpCodexClient (codex mcp-server), ExecCodexClient (codex exec --json). |
loop.ts |
Loop controller: goal → checklist → milestone → verify → review → follow-up → report. |
verifier.ts |
Reviewer/verifier: runs verification commands, parses git diff, evaluates checklist checks, computes completion. |
guards.ts |
Explicit safety guard checks (run config, outgoing prompt, observed diff). |
store.ts |
Logging + state store: JSON state, per-iteration logs, JSONL event log, checklist.md, final report, stop flag. |
config.ts |
Defaults, limits, guard thresholds, and the version-dependent Codex CLI launch settings. |
types.ts |
Shared TypeScript types / JSON state shapes. |
mcp-server.ts |
MCP server wrapper registering the 5 tools. |
cli.ts |
CLI wrapper driving the same modules. |
Requirements
- Node ≥ 20 (developed/tested on Node 24).
npm. - For real Codex runs: the OpenAI Codex CLI installed and authenticated (see below). Not required for the dry-run / tests.
Install & build
# from a clean clone:
npm install # installs pinned deps
npm run build # compiles src/ + test/ to dist/
npm test # builds, then runs the full test suite
npm test must finish with zero failures.
Quick start: the dry-run proof
Runs the full loop against the bundled sample project using the mock worker — no Codex, no network:
npm run dry-run
This is equivalent to:
node dist/src/cli.js run \
--dry-run \
--project-dir ./examples/sample-project \
--goal-file PROJECT_GOAL.md \
--verify "node greet.test.js"
It produces examples/sample-project/.codex-orchestrator/ with the checklist,
per-iteration logs, persisted state, and a final report. See the full captured
output in Worked end-to-end example.
The 5 MCP tools
Registered with exactly these names and input names:
start_project_loop
Start an autonomous loop; returns a run_id and runs in the background.
| Input | Type | Notes |
|---|---|---|
project_dir |
string | absolute path to the project |
goal_file |
string | default PROJECT_GOAL.md, relative to project_dir |
max_iterations |
int | default 10 |
verification_commands |
string[] | default [] |
sandbox |
enum | read-only | workspace-write | danger-full-access; default workspace-write |
approval_policy |
enum | on-request | never; default never |
codex_task
Send one prompt to Codex; returns its output + thread/session id. Outgoing prompts are guard-checked; a blocked prompt is not sent.
| Input | Type | Notes |
|---|---|---|
project_dir |
string | |
prompt |
string | |
thread_id |
string? | continue a prior Codex conversation |
review_current_state
Run git diff + verification, compare to the goal checklist, return remaining
gaps. Read-only; does not start a loop.
| Input | Type |
|---|---|
project_dir |
string |
goal_file |
string (default PROJECT_GOAL.md) |
verification_commands |
string[] |
get_loop_status
Return current iteration, latest Codex output, latest verification result, and
the next action for a run_id.
| Input | Type |
|---|---|
run_id |
string |
stop_loop
Request a clean cooperative stop of a run_id.
| Input | Type |
|---|---|
run_id |
string |
Why mode/max-runtime aren't tool inputs: the spec fixes the input names above, so the worker mode and the max-runtime limit are read from environment variables instead (
CODEX_ORCHESTRATOR_MODE,CODEX_ORCHESTRATOR_MAX_RUNTIME_MS). The max-runtime limit is still always enforced.
Register in Claude Code (exact config)
Add this to your project's .mcp.json (or merge into Claude Code settings).
Replace the absolute path. A copy is in .mcp.json.example:
{
"mcpServers": {
"codex-orchestrator": {
"command": "node",
"args": [
"/ABSOLUTE/PATH/TO/codex-orchestrator/dist/src/mcp-server.js"
],
"env": {
"CODEX_ORCHESTRATOR_MODE": "exec",
"CODEX_ORCHESTRATOR_MAX_RUNTIME_MS": "1800000"
}
}
}
}
Equivalent CLI registration:
claude mcp add codex-orchestrator \
-e CODEX_ORCHESTRATOR_MODE=exec \
-e CODEX_ORCHESTRATOR_MAX_RUNTIME_MS=1800000 \
-- node /ABSOLUTE/PATH/TO/codex-orchestrator/dist/src/mcp-server.js
To try it with no Codex installed, set CODEX_ORCHESTRATOR_MODE=mock.
Run
npm run buildfirst — the config points atdist/src/mcp-server.js.
The /massa command for Claude Code
commands/massa.md is a slash command that turns the raw
MCP tools into a guided flow. Install it by copying it into your Claude Code
commands directory:
# available in every project:
cp commands/massa.md ~/.claude/commands/massa.md
# or per-project:
cp commands/massa.md YOUR_PROJECT/.claude/commands/massa.md
Then, with the MCP server registered (previous section), type /massa (optionally
followed by a one-line idea) in Claude Code. The command:
- routes by size — a small task goes straight to
codex_task, a real build gets the full loop, and "where does the build stand?" usesreview_current_state; - inspects the repo first and only asks what it can't infer (goal, acceptance criteria, verification commands, constraints);
- writes
PROJECT_GOAL.mdwith a machine-checkable checklist and shows it to you before starting; - starts the loop with the safe defaults (
workspace-write, approvalnever) and polls status without spamming; - stops and asks you whenever a safety guard pauses the run — it never uses
danger-full-accessand never rephrases a prompt past a guard.
Worker modes
Selected via CODEX_ORCHESTRATOR_MODE (MCP server) or --mode / --dry-run (CLI):
| Mode | Transport | Use |
|---|---|---|
mock |
none (scripted) | dry-run / tests; applies steps from <project>/mock-plan.json (or an inline plan) |
exec |
codex exec --json per call |
default real path for Codex CLI 0.155+ |
mcp-server |
codex mcp-server over stdio (MCP SDK) |
explicit legacy mode for older CLIs that still provide this subcommand |
Installing & configuring the real Codex CLI
The orchestrator does not bundle Codex. For real runs, install + authenticate it. (Verified against the current Codex CLI; see Codex CLI compatibility.)
Install (pick one):
npm install -g @openai/codex # npm (provides the `codex` binary)
brew install --cask codex # Homebrew (note: --cask)
curl -fsSL https://chatgpt.com/codex/install.sh | sh # standalone script
Authenticate (pick one):
codex login # browser OAuth (ChatGPT sign-in)
codex login status # check
printenv OPENAI_API_KEY | codex login --with-api-key # API key via stdin
Verify the surface the orchestrator targets:
codex --help
codex exec --help # default worker transport
codex exec resume --help # continuation support
Only when explicitly selecting legacy --mode mcp-server on an older CLI,
check codex mcp-server --help. This subcommand was removed in Codex CLI 0.155;
it is separate from this package's own MCP server, which still exposes the five tools.
Config lives at ~/.codex/config.toml (CODEX_HOME defaults to ~/.codex).
The exec transport runs in the project directory and passes sandbox_mode and
approval_policy through per-call -c overrides; you do not need to pre-configure those.
CLI usage
codex-orchestrator run --project-dir <dir> [--goal-file PROJECT_GOAL.md]
[--verify "<cmd>" ...] [--max-iterations N]
[--sandbox workspace-write] [--approval-policy never]
[--max-runtime-ms N] [--mode mcp-server|exec|mock] [--dry-run]
codex-orchestrator review --project-dir <dir> [--goal-file ...] [--verify "<cmd>" ...]
codex-orchestrator task --project-dir <dir> --prompt "<text>" [--thread-id <id>] [--mode ...]
codex-orchestrator status --project-dir <dir> --run-id <id>
codex-orchestrator stop --project-dir <dir> --run-id <id>
--verify is repeatable. --dry-run forces --mode mock. Run run exits 0
on completion, 2 on a limit, 3 when paused for approval, 4 when stopped,
1 on error.
Examples:
# Foreground loop against a real project with Codex:
node dist/src/cli.js run --project-dir /path/to/app \
--verify "npm test" --verify "npm run build" --max-iterations 8
# One-shot review (no loop):
node dist/src/cli.js review --project-dir /path/to/app --verify "npm test"
The autonomous loop
Implemented exactly as specified (src/loop.ts):
- Read
PROJECT_GOAL.md. - Read relevant repo docs / manifests / existing tests.
- Produce an acceptance checklist →
.codex-orchestrator/checklist.md. - Ask Codex to implement the smallest coherent milestone.
- Run the configured verification commands.
- Review
git diffagainst the checklist. - If incomplete, send a targeted follow-up: what passed, what failed (exact commands/exit codes/errors), remaining gaps, what to fix next.
- Repeat until completion or a max-iteration / max-runtime limit.
- Produce a final report.
Safety guards & limits
Guards are explicit checks (src/guards.ts), evaluated at three points:
- Run config —
sandbox = danger-full-accessblocks;danger-full-access+neveris refused outright (validateSafetyConfig). - Outgoing prompt — blocks intents to deploy to production, purchase paid
services, access/exfiltrate secrets, weaken auth/security, mass-delete, or use
danger-full-access. - Observed diff — blocks changes outside the project root, edits to
secret/credential files (
.env,*.pem,~/.ssh, …), and large deletions (> 5 files or > 500 lines by default).
A block pauses the loop with status paused_for_approval and a
pending_approval record — it does not proceed without a human.
Hard limits (both always enforced, so the loop can never run forever):
- Max iterations — default 10 (
max_iterations). - Max runtime — default 30 min (
CODEX_ORCHESTRATOR_MAX_RUNTIME_MS/--max-runtime-ms). Per-Codex-call and per-verification timeouts also apply.
Defaults: sandbox workspace-write, approval never (valid only inside
the workspace confinement).
State & logs layout
Everything lives under <project>/.codex-orchestrator/:
.codex-orchestrator/
├── checklist.md # spec-mandated path (latest run)
└── runs/<run_id>/
├── state.json # persisted RunState (source of truth)
├── checklist.md # per-run copy
├── events.jsonl # append-only structured event log
├── final-report.md
├── stop.flag # present => cooperative stop requested
└── iterations/
├── iter-001.json / iter-001.md
└── ...
The JSONL event log records every prompt_sent, codex_response,
verification, review, guard, decision, paused, and run_finished.
Worked end-to-end example
The bundled examples/sample-project/ has a goal (implement greet()), a
verification test (node greet.test.js), and a mock-plan.json whose first step
writes a wrong greeting (so verification fails and a follow-up is sent) and
whose second step fixes it.
$ npm run dry-run
▶ run run-64cd35db (mode=mock, sandbox=workspace-write, approval=never)
📋 checklist: 3 item(s) → .../examples/sample-project/.codex-orchestrator/checklist.md
── iteration 1/10 ──
→ codex (mock) prompt sent (2953 chars)
← codex responded (95 chars)
🧪 verification: 0/1 passed
✔ review: 33% checklist, 3 gap(s)
── iteration 2/10 ──
→ codex (mock) prompt sent (981 chars)
← codex responded (104 chars)
🧪 verification: 1/1 passed
✔ review: 100% checklist, COMPLETE
🏁 COMPLETED — all checklist items satisfied and verification passed
Final status: completed — all checklist items satisfied and verification passed
State dir: .../examples/sample-project/.codex-orchestrator/runs/run-64cd35db
Checklist: .../examples/sample-project/.codex-orchestrator/checklist.md
Final report: .../examples/sample-project/.codex-orchestrator/runs/run-64cd35db/final-report.md
Resulting checklist.md:
# Acceptance Checklist
- [x] **greet-file** — src/greet.js exists and exports greet()
- evidence: file exists: src/greet.js
- [x] **greet-impl** — greet() returns a 'Hello, ...' greeting
- evidence: file src/greet.js matches /Hello/
- [x] **tests-pass** — the greet test passes
- evidence: command passed: node greet.test.js
Resulting final-report.md (iteration log):
## Iteration log
- Iteration 1: continue — 3 gap(s) remain; sending a follow-up (verification 0/1)
- Iteration 2: done — all checklist items satisfied and verification passed (verification 1/1)
Running it for real (with Codex): drop the --dry-run flag and ensure Codex
is installed/authenticated. The loop will use codex exec --json, threading the
conversation across iterations via codex exec resume <thread_id>. To exercise the real
git diff review on the sample, git init the target first:
cd examples/sample-project && git init -q && git add -A && git commit -qm baseline && cd -
node dist/src/cli.js run --project-dir ./examples/sample-project --verify "node greet.test.js"
Codex CLI compatibility
The Codex flag/tool surface drifts between versions. All version-dependent names
are centralized in config.ts (DEFAULT_CODEX_CLI) so they can
be adjusted in one place. The default exec transport targets Codex CLI 0.155+:
- Legacy MCP only:
codex mcp-server(over stdio), on older CLIs that still provide it. Notcodex mcp serve(codex mcpis the separate "manage external servers" command). - Legacy MCP tools:
codex(start) andcodex-reply(continue). Thecodextool takes kebab-case args (prompt,cwd,sandbox,approval-policy) and rejects unknown fields;codex-replytakes camelCase{ threadId, prompt }. - Legacy MCP session id: returned in
structuredContent.threadId; reused asthreadId. - Default exec:
codex exec --json -c 'sandbox_mode="workspace-write"' -c 'approval_policy="never"' "<prompt>"; resume withcodex exec resume <id>. The JSONL stream is tagged by dottedtype(thread.startedcarriesthread_id; the final answer is in anitem.completedwhoseitem.type === "agent_message", fieldtext). A legacyEventMsgfallback parser is included. - Sandbox values:
read-only|workspace-write|danger-full-access. - Approval values:
on-request|never. Retireduntrustedandon-failurevalues are rejected before execution, including in legacy mode. Codex's granular approval objects are not exposed by this package's string API. - Exec failures: nonzero exits, signals, and timeouts fail the task even if
stdout contains a partial reply. CLI tasks exit nonzero with diagnostics; MCP
tasks return
status: "error". Loops retain the error as a gap and cannot complete that iteration merely because existing verification checks pass. - Guarded:
--dangerously-bypass-approvals-and-sandbox/--yoloand--sandbox danger-full-accessare never emitted.
If a future Codex renames a tool or flag, edit DEFAULT_CODEX_CLI — no other
code changes are needed.
To check the supported string policies against a real CLI without credentials or
a model call, run node scripts/check-codex-policies.mjs [path/to/codex].
It uses an empty temporary CODEX_HOME, a read-only sandbox, and an intentionally
missing output schema to stop accepted policies before task execution; retired
policies must fail CLI argument validation.
Troubleshooting
- "Goal file not found" — pass
--project-dirpointing at the dir that containsPROJECT_GOAL.md, and--goal-filerelative to it. get_loop_statussays "Unknown run_id" — for cross-process lookups the server scans the server's cwd. Launch the MCP server from the project dir, or use the CLIstatuscommand with--project-dir.- Real Codex run errors immediately — run
codex login statusandcodex exec --help; confirm the binary is onPATH(override with theCODEX_BINenv var). - Git diff shows "(not a git repository)" — the diff-based guards/review need
a git repo;
git initthe target. The checklist + verification still work without git. - Loop paused unexpectedly — check
get_loop_status→pending_approval; a safety guard tripped. Review the change, then re-run with adjusted scope.
### Verifier regression hardening (October 2026)
- A checklist item without a machine check requires at least one actual passing
verification command. An empty verification list is not evidence of success.
- File checks require an existing regular file with both lexical and resolved
paths inside the project. Escaping symlinks are rejected. This is a defensive
check, not an OS sandbox against concurrent malicious filesystem rewrites.
- Git change capture uses NUL-delimited paths, preserving whitespace, quotes,
tabs/newlines and literal ` -> ` text. Renames appear as delete/add so both
affected paths reach the guards.
- Untracked symlinks are not followed for line counts. A final newline no longer
adds a phantom line to the change totals.
`npm test` runs the mocked integration suite, not Codex inference. The added tests
use temporary synthetic Git projects. Actual model/CLI behavior is not certified
by these checks; no model calls are needed to execute the suite.
codex-orchestrator MCP questions
What tools does codex-orchestrator MCP provide?
It exposes 9 tools, including project_dir, goal_file, max_iterations, verification_commands, sandbox.
Can I test the orchestrator without an API key?
Yes, you can use the dry-run mode which uses a mock worker to prove the loop end-to-end with no real Codex call and no network.