# codex-supervisor-mcp [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/zriyox/codex-supervisor-mcp  
**GitHub Stars:** 3  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/codex-supervisor-mcp

## Description
Parallel Codex CLI workers from any MCP client: one git worktree each, state in SQLite, web board.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "codex-supervisor-mcp": {
    "command": "npx",
    "args": ["-y","codex-supervisor-mcp"]
  }
}
```

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/codex-supervisor-mcp/readme_