codex-mcp-swarm
Run and manage OpenAI Codex CLI sessions through MCP, including parallel background tasks with live monitoring.
Execute Codex synchronously with official-compatible parameters such as model, sandbox, approval policy, cwd, profile, config, and instructions.
Launch async tasks in parallel and collect results in one batch with
codex_wait.Monitor running or completed tasks with
codex_status, including tools called, last command, reasoning, progress, warnings, and failure details.Cancel running async tasks while preserving worktrees and partial output for inspection.
Continue prior Codex sessions using
codex_replyor async tasks withthreadId.Isolate parallel tasks in separate git worktrees/branches to avoid conflicts, then merge results.
Read MCP resources for server info, config, and task state.
Configure server defaults via
-c key=value, flags, and environment variables.
Wraps OpenAI's Codex CLI for parallel execution, live monitoring, and worktree isolation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@codex-mcp-swarm run three parallel code reviews with worktree isolation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: truecreates an isolated git worktree per task so parallel Codex instances never edit past each otherBatch wait -- launch N tasks, call
codex_waitonce, get all results when they finishLive 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=valueserver args ascodex mcp-server
Related MCP server: multi-agent-mcp
Tools
Tool | Description |
| Synchronous execution (drop-in replacement for official); terminal failures include the model, structured cause, category, and retryability |
| Launch a task, get a |
| Continue a previous session via |
| Live view: tools called, last command, current thinking, warnings, and terminal failure cause |
| Block until multiple tasks complete and return results or structured failure details |
| Kill a running async task (preserves worktree for inspection); if it already failed, return the recorded cause |
Installation
Claude Code
claude mcp add codex-swarm -- uvx --upgrade codex-mcp-swarm \
-c model=gpt-6-astra \
-c approval_policy=never \
-c sandbox_mode=danger-full-access \
--skip-git-repo-checkThat'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, usepipx run codex-mcp-swarminstead ofuvx codex-mcp-swarm.
Manual (~/.claude.json)
{
"mcpServers": {
"codex-swarm": {
"type": "stdio",
"command": "uvx",
"args": [
"--upgrade",
"codex-mcp-swarm",
"-c", "model=gpt-6-astra",
"-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 resultsCollecting 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
FAILEDfromcodex_statusorcodex_waitthat is flagged as inferred is a prompt to verify, not a conclusion. Checkpgrep -af 'codex exec', file mtimes, the worktree branch, and your own build or tests.A
codex_waitthat times out is not a failure at all. The task is not killed. Callcodex_waitagain with the sametask_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/def456Each 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 contextcodex_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
Flag | Description |
| Config default (repeatable). Same format as |
| Allow running outside git repos. |
| Don't persist session files. Disables |
Per-call parameters
All parameters from the official Codex MCP tool are supported:
prompt(required)model-- override server defaultsandbox--read-only,workspace-write,danger-full-accessapproval-policy--untrusted,on-failure,on-request,nevercwd-- working directoryprofile-- config profile fromconfig.toml(ignored onthreadIdresumes --codex exec resumehas no--profileflag)config-- object of key=value overridesworktree-- 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 |
| Version, capabilities, directories, config |
| Current server-level defaults and flags |
| All known tasks and their current state; failed entries include model, cause, category, and retryability |
Environment variables
Variable | Default | Description |
|
| Log file path |
|
| Log level ( |
|
| Task output storage directory |
|
| Worktree storage directory |
|
| Seconds before completed task artifacts (and worktrees) are cleaned up |
|
| Floor in seconds for |
| (auto) | Windows only: path to |
On Windows the /tmp/... defaults become the per-user temp directory (%TEMP%).
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)Works on Windows (native, no WSL): PID reuse protection via process creation time, cancellation kills the whole process tree
Windows notes
An npm-installed Codex is a
codex.cmdshim. The server resolves it tonode .../@openai/codex/bin/codex.jsand never runs Codex throughcmd.exe, which would cut multi-line prompts at the first newline and interpret& | < > ^ %. If Codex lives elsewhere, setCODEX_SWARM_CODEX_BIN.Children are started without a console window and in their own process group. Async tasks are not tied to the server process, but if the MCP client runs the server inside a kill-on-close job object, they end with it.
The Windows command line is limited to 32,767 characters, which caps prompt plus instructions per call.
Codex itself needs a Windows sandbox backend. Without one (
codex doctorshowssandbox backend disabled),read-only/workspace-writecalls withapproval-policy: neverreject every shell command as "blocked by policy". Set it in~/.codex/config.toml(unelevatedneeds no admin rights):[windows] sandbox = "unelevated"
Credits
Originally inspired by jeanchristophe13v/codex-mcp-async. Rewritten with full flag parity, JSONL status parsing, batch wait, and session reply support.
License
MIT
Available Tools
6 toolscodexB
Run a Codex session synchronously. Parameters match the official Codex MCP tool.
Inputs: prompt (required), approval-policy, sandbox, cwd, +7 more.
codex_asyncA
Start a Codex task in the background and return immediately with a task_id. Use codex_wait to collect results from one or more tasks, or codex_status to monitor progress. Set worktree=true to isolate each task in its own git worktree so parallel tasks don't conflict -- merge the branch back when done.
Inputs: prompt (required), approval-policy, sandbox, cwd, +7 more.
codex_cancelA
Kill a running async Codex task. The process is terminated and the task is marked as cancelled. Any worktree and partial output are preserved for inspection.
Inputs: task_id (required).
codex_replyA
Continue a Codex conversation by providing the thread/session ID and a follow-up prompt. Uses codex exec resume under the hood.
Inputs: threadId (required), prompt (required).
codex_statusA
Get live status of running async Codex tasks. Shows what each task is currently doing: last tool call, reasoning, progress. Works on both running and completed tasks.
Inputs: task_ids (required).
codex_waitA
Block until one or more async Codex tasks complete, then return all results. Accepts a list of task_ids. This avoids repeated polling -- call once after launching codex_async tasks. Default timeout is 1800s (30 min). If a task times out, it is NOT killed -- it keeps running. You can call codex_wait again with the same task_ids to resume waiting, or use codex_status to check progress.
Inputs: task_ids (required), timeout.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: sync execution, async launch, cancel, reply, status polling, and waiting. No two tools overlap in functionality.
Most tools follow the 'codex_' prefix with a clear verb, but the sync tool is simply 'codex' without an underscore, creating a minor inconsistency.
6 tools is appropriate for managing Codex sessions, covering sync and async operations, cancellation, continuation, status, and blocking wait.
Core lifecycle is well-covered (start, wait, cancel, continue, monitor). Minor gap: no tool to list all active tasks, though status can query known task IDs.
Maintenance
Related MCP Connectors
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Run your AI-run company from Claude Code, Codex, Cursor or ChatGPT: inbox, tasks, team, Studio.
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables parallel execution of shell commands and AI coding agents (Claude, Gemini, Codex) across lists of items like files or URLs, with batched processing and real-time streaming output for batch operations.8172 npm6Apache 2.0
- AlicenseCqualityDmaintenanceManages multiple AI CLI instances (Claude Code, Codex, Gemini, Cursor) in tmux sessions for parallel task execution, with optional git worktree support.90MIT
- AlicenseNot gradedqualityCmaintenanceEnables coordinating Claude Code and Codex on one machine by fanning out tasks to multiple agents in isolated Git worktrees, comparing results, picking a winning candidate, and handing off work between harnesses. It provides MCP stdio tools, a CLI, and a local loopback web cockpit.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables a primary agent to dispatch, wait on, and supervise multiple parallel Codex CLI workers, each running in its own isolated Git worktree with conflict-checked path ownership. Persists every worker's state, goals, and event stream to disk so work can be tracked, resumed, reconnected, searched, and cancelled across restarts.433 npm3MIT