Codex Supervisor MCP

What codex-supervisor-mcp does

The codex-supervisor-mcp MCP server lets a main agent delegate separate tasks to multiple Codex CLI workers. Each worker runs in a Git worktree on a codex/<taskId> branch, reducing file collisions between concurrent jobs. The main agent decides how to review, combine, or reject the resulting changes.

Work is grouped with a shared session_id, and a required goal.objective records the intended outcome. Required ownedPaths identify the files a worker is allowed to affect and are checked against currently running workers when work is dispatched. The server records state in SQLite and writes event streams to JSONL files, so a restarted main process can recover session and worker information.

The project fits the 🤖 Coding Agents category. It is useful for splitting independent tests, modules, or other repository tasks into parallel units while keeping the main conversation focused on task descriptions and results rather than every worker event.

How it works

create_codex_worker starts a Codex process with task context, constraints, optional commands, time limits, model settings, and a base Git reference. wait_codex_workers returns snapshots until selected workers reach a terminal state; compact responses help limit context size. Results include the worker's report, commands and exit codes from its own verification, changed files, and the supervisor's acceptance result.

The codex-supervisor-mcp MCP server separates worker failure from a lost process and preserves the Codex thread_id for later continuation. resume_codex_worker continues the same Codex session, while create_codex_followup_worker starts a new session with prior task information. ask_codex_worker creates a read-only side conversation for questions without changing the active worker.

Before integration, land_codex_worker cherry-picks the worker's changes into the current branch. It can create a commit for uncommitted changes, rejects a failed acceptance check by default, and rolls back on conflicts. A rebase target can be supplied when the main branch has advanced.

Setup and configuration

Install Node.js 22.13.0 or newer and make sure the codex command is available on PATH. Install the package globally with npm install -g codex-supervisor-mcp. Installation scripts may register the MCP server and skills for detected Claude Code or Codex installations; otherwise, the README provides explicit claude mcp add and codex mcp add commands.

Start the optional board with codex-supervisor-web, then open http://127.0.0.1:7877. SUPERVISOR_WEB_PORT changes the port. The state directory is selected using SUPERVISOR_HOME, then a nearby .mcp.json, then ~/.codex-supervisor.

Tools and capabilities

The server exposes tools for:

• Creating, resuming, following up, waiting for, listing, inspecting, and cancelling Codex workers.
• Reading summaries, goals, reports, diffs, status details, and raw events.
• Searching previous work and retrieving all workers in a session.
• Running acceptance commands before dispatch or after a worker exits.
• Checking orchestration state, updates, and session metadata.
• Landing verified changes onto an integration branch.

Acceptance commands run with Bash errexit and pipefail. They receive task, base-commit, and run-count environment values. Structured reports can identify required, skipped, or changed failures; missing required checks and stale reports do not pass. Windows requires Git for Windows Bash.

Limitations and notes

The web board is read-only: it displays sessions, workers, commands, reports, events, task prompts, and side questions but does not dispatch or cancel work. ownedPaths are checked when a worker is created and do not continuously prevent later changes. The main agent remains responsible for reviewing diffs and choosing what to land.

Acceptance output is truncated for display, but its exit code is preserved. Timeouts fail acceptance even if the terminated command later exits successfully. A reportPath must stay inside the worktree, and temporary test reports should be kept out of changes intended for integration.