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

Tool	Description
codex	Synchronous execution (drop-in replacement for official)
codex_async	Fire-and-forget -- returns a task_id immediately
codex_reply	Continue a previous session via codex exec resume
codex_status	Live view: tools called, last command, current thinking
codex_wait	Block until multiple tasks complete, return all results
codex_cancel	Kill a running async task (preserves worktree for inspection)

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

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")

Server flags

Flag	Description
-c key=value	Config default (repeatable). Same format as codex mcp-server.
--skip-git-repo-check	Allow running outside git repos.
--ephemeral	Don't persist session files. Disables codex_reply.

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

URI	Description
codex-swarm:///server-info	Version, capabilities, directories, config
codex-swarm:///config	Current server-level defaults and flags
codex-swarm:///tasks	All known tasks and their current state

Environment variables

Variable	Default	Description
CODEX_SWARM_LOG	/tmp/codex_mcp_swarm.log	Log file path
CODEX_SWARM_LOG_LEVEL	WARNING	Log level (DEBUG, INFO, WARNING, ERROR)
CODEX_SWARM_TASK_DIR	/tmp/codex_swarm_tasks	Task output storage directory
CODEX_SWARM_WORKTREE_DIR	/tmp/codex-swarm-worktrees	Worktree storage directory
CODEX_SWARM_TASK_MAX_AGE	86400 (24h)	Seconds before completed task artifacts (and worktrees) are cleaned up

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