codex-mcp-swarm

An MCP server that wraps OpenAI's Codex CLI with true parallel execution and live task monitoring. Zero dependencies -- single Python file, stdlib only.

Why?

The official codex mcp-server processes requests sequentially. If your MCP client (Claude Code, etc.) needs to run 5 Codex tasks, they queue up one after another. This server spawns each task as an independent subprocess, so they run in parallel.

Unique features no other Codex MCP wrapper has:

• Worktree isolation -- worktree: true creates an isolated git worktree per task so parallel Codex instances never edit past each other
• Batch wait -- launch N tasks, call codex_wait once, get all results when they finish
• Live status -- see what each Codex task is doing right now (last tool call, current reasoning, progress)
• Full flag parity -- same parameters as the official Codex MCP tool (sandbox, approval-policy, cwd, model, config, etc.)
• Drop-in config -- accepts the same -c key=value server args as codex mcp-server

Tools

Installation

Claude Code

claude mcp add codex-swarm -- uvx --upgrade codex-mcp-swarm \
  -c model=gpt-5.4 \
  -c approval_policy=never \
  -c sandbox_mode=danger-full-access \
  --skip-git-repo-check

That's it. No clone, no setup. uvx downloads and runs it directly from PyPI. The --upgrade flag ensures you always get the latest version on restart.

Note: Requires uv (curl -LsSf https://astral.sh/uv/install.sh | sh). Alternatively, use pipx run codex-mcp-swarm instead of uvx codex-mcp-swarm.

Manual (~/.claude.json)

{
  "mcpServers": {
    "codex-swarm": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--upgrade",
        "codex-mcp-swarm",
        "-c", "model=gpt-5.4",
        "-c", "approval_policy=never",
        "-c", "sandbox_mode=danger-full-access",
        "--skip-git-repo-check"
      ]
    }
  }
}

The -c flags are identical to codex mcp-server -- copy-paste your existing config.

Usage

Parallel execution

1. Call codex_async with prompt A  -->  task_id: "abc123"
2. Call codex_async with prompt B  -->  task_id: "def456"
3. Call codex_async with prompt C  -->  task_id: "ghi789"
4. Call codex_wait(task_ids=["abc123", "def456", "ghi789"])
   --> blocks until all finish, returns all results

Collecting results: read this before you fan out

A task_id is internal to this server. Your MCP client does not track it. It will not appear in a task list, and no notification fires when the task finishes. If the agent's turn ends before codex_wait is called, the Codex run still completes and writes its result to disk, but nothing is left to deliver it and nothing wakes the session. codex_status is a progress peek only; it collects nothing.

So: codex_async and codex_wait belong in the same turn.

Let the wait run long. Claude Code moves any main-conversation tool call still running after two minutes into a tracked background task and re-invokes the session with the result when it settles -- that is the wake-up mechanism, so crossing the two-minute line is the goal rather than something to dodge. Short timeout values are raised to a floor (default 150s, override with CODEX_SWARM_MIN_WAIT) for exactly this reason. Tasks that have already finished return instantly regardless of the floor.

Failure reporting and terminal precedence

codex exec writes progress, warnings and sandbox notices to stderr on perfectly healthy runs. Until 1.10.0, a task whose exit code was lost to a reaping race was marked failed on the strength of non-empty stderr alone, so finished work got reported as a failure and callers acted on it.

Version 1.11.0 uses the terminal events in codex exec --json as the primary lifecycle signal. An unambiguous turn.completed means success even if an earlier top-level error event was emitted while the CLI retried. An unambiguous turn.failed means failure even if an earlier, partial agent_message exists. Top-level error events are diagnostic rather than terminal, because the public JSONL omits the CLI's internal will_retry field; item.completed events whose item type is error are warnings. If terminal events are absent or contradict each other, an observed process exit code decides the result. Only a verdict made without either signal is marked as inferred, and both completion and failure outputs label that explicitly.

Terminal failures report the model parsed from the command that actually ran, the structured turn.failed.error.message, a failure category, whether a later retry is likely to be useful, and a suggested action. Retryability is information only: the wrapper never starts a second Codex turn. The Codex CLI may perform its own in-turn retries. Stderr can be included as a clearly labeled, truncated diagnostics section, but it never replaces the primary failure cause.

Two things follow for anyone consuming this server:

• A FAILED from codex_status or codex_wait that is flagged as inferred is a prompt to verify, not a conclusion. Check pgrep -af 'codex exec', file mtimes, the worktree branch, and your own build or tests.
• A codex_wait that times out is not a failure at all. The task is not killed. Call codex_wait again with the same task_id.

Worktree isolation

Prevent parallel tasks from editing the same files:

1. Call codex_async(prompt="Refactor auth", worktree=true)
   --> task_id: "abc123"
   --> Worktree Branch: codex-swarm/abc123

2. Call codex_async(prompt="Add logging", worktree=true)
   --> task_id: "def456"
   --> Worktree Branch: codex-swarm/def456

3. codex_wait(task_ids=["abc123", "def456"])
4. git merge codex-swarm/abc123
5. git merge codex-swarm/def456

Each task gets its own git worktree and branch based on HEAD. After completion, merge the branches back. Worktrees are automatically cleaned up after 24 hours (configurable via CODEX_SWARM_TASK_MAX_AGE).

Live monitoring

Call codex_status(task_ids=["abc123"])
-->
=== Task abc123 (45s elapsed) ===
Phase: running
Tools called: 23
Last tool: exec_command(grep -rn "handleError" src/)
Output: Analyzing error handling patterns across the codebase...

Session continuity

1. Call codex(prompt="Review this file")  -->  result + session persisted
2. Call codex_reply(threadId="<session-uuid>", prompt="Now fix the bug you found")

For a follow-up that will run more than a few minutes, resume in the background instead -- codex_async accepts threadId and gives you a task_id that survives a client idle timeout:

1. Call codex_async(threadId="<session-uuid>", prompt="Now implement it")
                                          -->  task_id: "abc123"
2. Call codex_wait(task_ids=["abc123"])   -->  result, with full prior context

codex_reply is synchronous and emits progress notifications while it waits, but a client that gives up on silence will still abandon the request. Only the async path leaves you a handle to recover with.

Server flags

Per-call parameters

All parameters from the official Codex MCP tool are supported:

• prompt (required)
• model -- override server default
• sandbox -- read-only, workspace-write, danger-full-access
• approval-policy -- untrusted, on-failure, on-request, never
• cwd -- working directory
• profile -- config profile from config.toml (ignored on threadId resumes -- codex exec resume has no --profile flag)
• config -- object of key=value overrides
• worktree -- run in an isolated git worktree (prevents parallel tasks from conflicting)
• base-instructions, developer-instructions, compact-prompt

MCP Resources

The server exposes read-only resources for discoverability:

Environment variables

Requirements

• Python 3.8+
• Codex CLI installed and authenticated
• No pip dependencies (stdlib only)
• Works on Linux and macOS (Linux gets extra PID reuse protection and zombie detection via /proc)

Credits

Originally inspired by jeanchristophe13v/codex-mcp-async. Rewritten with full flag parity, JSONL status parsing, batch wait, and session reply support.

License

MIT