Codex Supervisor Mcp

io.github.zriyoxv0.7.3Updated Oct 7, 2026

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

VerifiedSTDIODesktop onlyDeveloper ToolsDatabasesProductivity & Workflow

Overview

AI-generated overview

Lets an assistant dispatch and supervise several parallel Codex CLI coding workers, each in its own Git worktree, with state in SQLite and a local web board.

What it does
A main MCP client session creates Codex CLI workers, each with its own Git worktree, declared ownedPaths and a goal, and runs them in parallel. Tools wait for workers, return their reports, diffs, events and status, ask a worker a read-only side question, resume the same Codex session, and cherry-pick a worker's commits into the integration branch. State is stored in SQLite and raw JSONL under a state directory, and a separate local web board shows sessions, workers, commands and diffs.
When to use it
Use it when one repository needs several coding agents working at once and you want file-level isolation, durable state across restarts, and a main session that stays small by reading summaries and diffs instead of full worker output. It suits multi-step tasks where each worker does one step and the main session reviews and lands the result. It is not needed for single-agent or single-file edits.
Requirements
Local process over stdio; Node.js 22.13.0 or newer and the codex CLI on PATH (or CODEX_BIN set to its path). Install from npm; postinstall registers the MCP server and skill, which GUI clients must configure manually. State lives under SUPERVISOR_HOME (default ~/.codex-supervisor); the web board uses SUPERVISOR_WEB_PORT and SUPERVISOR_WEB_HOST. No authentication is declared.
Before you install
Workers run the Codex CLI and can edit files, run commands and create commits in Git worktrees; the default workspace-write sandbox blocks commits, and danger-full-access removes that protection. Review each worker's diff before landing it, since ownedPaths is only checked at dispatch and cannot stop a worker creating files outside its list. The server checks the npm registry for updates and can install a new global version in the background; CODEX_SUPERVISOR_NO_UPDATE_CHECK and CODEX_SUPERVISOR

Installation

In SourceWeft

  1. Open Codex Supervisor Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

codex-supervisor-mcp

English | 中文

[npm version] [npm downloads] [license] [CI] [node]

官网 codex-supervisor.zriyo.com · 给模型读的 llms.txt

让几个 agent 同时改一个仓库，结果是互相覆盖、没人说得清谁改了什么，主线程的上下文还被 worker 的输出塞满。

codex-supervisor-mcp 是一个 Codex MCP server，把「派单」和「记账」从模型上下文里拿出来放到磁盘上：一个主线程（Claude Code、Codex 或任何 MCP 客户端）同时指挥多个 Codex CLI worker，一个 worker 一个 Git worktree，状态落盘到 SQLite，附一个网页看板。

[演示：一个 Claude Code 主线程同时派 3 个 Codex worker，各自独立 worktree，并行跑完后合并提交]

30 秒真跑：create_codex_worker ×3，三个 worker 各自 worktree 并行，主线程收 3 份 diff 合成一次 commit。

解决什么

问题做法
几个 worker 互相踩文件一个 worker 一个 Git worktree，ownedPaths 在派单前查冲突
worker 的过程塞爆主线程上下文事件写 data/runs/<taskId>.jsonl，读的时候有 limit / maxChars / kinds 三道闸
主线程读一次状态就顶满get_orchestration_overview 把全部 worker 压进 7000 字节
进程重启后不知道谁还在跑supervisor.sqlite 一行一个 work，带 thread_id
换个会话接不上之前的 workerresume_codex_worker 走 codex exec resume <thread_id>，接的是同一个 Codex 会话
分不清「跑失败」和「进程没了」状态机把 failed 和 lost 分开
看不见一批活现在到哪了codex-supervisor-web 开一个看板，按 session 看每路 worker 在干什么

worker 跑的是 codex exec，model 透传：主线程留在 Claude，worker 可以挂 DeepSeek 或任何 Codex 配了 provider 的模型，账单分开算。

五分钟跑起来

前置：Node.js 22.13.0 以上，codex CLI 在 PATH 里。macOS、Linux、Windows 都行。

1. 装

bash
npm install -g codex-supervisor-mcp

postinstall 装 skill、注册 MCP。claude mcp list 里没看到（npx、pnpm、--ignore-scripts 不跑 postinstall）就手动补：

bash
claude mcp add -s user codex-supervisor -- npx -y codex-supervisor-mcpcodex mcp add codex-supervisor -- npx -y codex-supervisor-mcp

重启 Claude Code / Codex。以后不用再手动更，见「更新」。只要 skill 不要 MCP：npx skills add zriyox/codex-supervisor-mcp。

2. 派第一批活

在 Claude Code 里直接说人话，skill 会让它走正确的流程：

把这三个模块的单测补齐，用 codex-supervisor 分三路并行跑，session 叫「补单测」。

主线程背后做的事（你也可以自己调工具）：

create_codex_worker ×3   每路带 session_id、session_title、ownedPaths、goalwait_codex_workers       默认等 2 分钟，到点返回快照，没完就接着等get_worker_result ×3     收每路的完整汇报和改动清单

每路的改动在各自的 codex/<taskId> 分支上，合不合、怎么合由主线程定。

3. 开看板

bash
codex-supervisor-web# 没全局装也能起：npx -p codex-supervisor-mcp codex-supervisor-web

打开 http://127.0.0.1:7877。状态目录按 SUPERVISOR_HOME、最近的 .mcp.json、~/.codex-supervisor 的顺序找；端口用 SUPERVISOR_WEB_PORT 改。看板只看，不派单不取消。

我自己怎么用

能连 MCP 的都能当主线程，这里只是我的用法。我开两个 Claude Code 会话，一个只管文档，一个只管派活：一个会话又写详设又盯 worker，上下文两小时就满。

谁开在哪管什么
我定需求，拍板，看汇报
规划会话需求和文档仓聊需求，写详设，每一块活写一份任务书，末尾附一段发给主脑的话
主脑会话代码仓的一个 worktree读任务书，派 Codex worker，核每路的 diff，把结果填回任务书，向我汇报。不写业务代码
Codex worker各自的 worktree一个 worker 做一步，一个提交，在远端机器上编译和验证。不 push，不合并

两个会话之间只传一段文字，粘进主脑会话用 /goal 接上。结构固定：

text
【角色】   你是主脑：读文档和代码，派 worker，核结果，更新文档，向我汇报。不写业务代码。           派活和盯进度用 codex-supervisor 这个 skill，开工前先加载它。【背景】   这一块为什么做，上一块留下了什么【先读】   哪几份文档的哪几节。几份说法不一样时以哪份为准【仓和分支】工作目录在哪，各分支现在在哪个提交，哪些分支只读【做什么】 照任务书第几节那张表做。一步一个提交，这步验证过了才做下一步。表里没有的不做【派活】   先 search_works 看有没有派过，别重复           整批用同一个 session_id           改同一批文件就串行，文件完全不重叠才并行，每路 ownedPaths 写清           一个 worker 只做一步。task 写全：背景、文档出处、要改的文件、验证命令、输出格式           worker 交回来先看 diff。它说过了不算，你看到才算【构建和测试】全走远端机器，本机不跑【红线】   不改什么，不推什么，不读什么【必须停下来问我】【汇报】   中文，表格优先，报哪几项，然后停下来等我

主脑一轮下来调的工具：

search_works            查这批活派过没有create_codex_worker     一步一个 worker，同一个 session_id，ownedPaths 不重叠wait_codex_workers      2 分钟一轮，compact: true，没完接着调get_worker_result       它说自己做了什么get_worker_diff         它实际做了什么ask_codex_worker        对不上就问它为什么，只读，不动它的线程resume_codex_worker     要改就追一条，让它 amend 进原来那个提交land_codex_worker       核过了，落进集成分支

上一块活 25 步，主脑会话一个人从第 1 步盯到第 25 步，上下文里只有任务书和每路交回来的汇报，没被 worker 的过程撑爆。

为什么一个 worker 只做一步：第 5 步做错了，让做第 5 步的那个 worker resume_codex_worker 一下，改完 --amend 并回它自己那个提交，主脑再核一次，过了才落进集成分支。要是一个 worker 连做了 5、6、7 三步，第 5 步错了就没法这样改，6 和 7 的提交已经叠在 5 上面，改 5 得连 6、7 一起重做。

看板里有什么

位置内容
左栏每个 session 一行：标题、worker 数、几路在跑、最近活动。左下角是版本和更新提示
session 页统计（总数 / 运行中 / 完成 / 失败 / 丢失），有 worker 在跑时列每路正在执行的命令
worker 台账一行一路：状态、标题、正在跑的命令或最后一句汇报、耗时、改了几个文件、跑了几条命令
worker 抽屉七个 tab：概览、汇报、改动、命令、事件、任务书、旁问
旁问对这路 worker 提问，就是 Codex 的 /btw：从它的线程 fork 出只读旁路会话来答，不碰它正在跑的活。多轮、可中断、换标签页回来自动接上

浅色深色跟系统走，没有外网资源。

工具

19 个。

工具入参作用
create_codex_workertask, cwd, ownedPaths, goal, session_id, session_title, session_note, dependsOn, baseRef, sandbox, model, reasoningEffort, title, skipGitRepoCheck起一个 worker。baseRef 指定 worktree 从哪个提交切，默认 HEAD，接着另一路干就填它的 codex/<id>
create_codex_followup_workertask_id, followup_prompt, session_id, 其余同上开一个新会话，把老 worker 的 prompt、状态、近期事件拼进去
resume_codex_workertask_id, prompt接同一个 Codex 会话继续跑，thread_id 不变
wait_codex_workerstask_ids, mode(any/all), timeoutMinutes, timeoutMs, compact, includeEvents, eventLimit, eventMaxChars, eventKinds等终态。默认 2 分钟，到点带快照返回，worker 照跑；compact 每路只回一行
get_orchestration_overviewstatus, limit全部 worker 的状态表，封顶 7000 字节。带 version 和 update
get_worker_resulttask_id, limit, maxCharsworker 自己的完整汇报，外加 status / exit_code / changed_files
get_worker_difftask_id, maxChars, pathsworker 实际改了什么：从 worktree 起点到工作区的 patch，提交没提交都算。maxChars 管总量，超了的文件只列名
ask_codex_workertask_id, question, timeoutMs, maxChars, fresh, end旁路问 worker 一句。线程 fork 成只读侧会话，没网络、没 MCP 工具，worker 本身不动。worker 被 resume 过会自动换新 fork，fresh 强制换，end 删
land_codex_workertask_id, onto, commitMessage把 worker 在 codex/<id> 上的提交 cherry-pick 到派单目录的当前分支。目标必须干净，冲突就回滚。commitMessage 先替它把未提交的改动提交成一笔
get_worker_summarytask_id一段话：goal、状态、改动、最后一条命令和消息
get_codex_worker_statustask_id, includePrompt, promptMaxChars单个 worker 的状态细节
get_codex_worker_eventstask_id, limit, maxChars, kinds原始事件流
get_worker_goaltask_id派单时记的 goal + Codex 原生 goal（token、用时）
list_codex_workersstatus, includeHistory, includeDetails列 worker，默认只看在跑的
get_session_workssession_id一个 session 的全部 worker。主线程重启后靠它找回那批活
describe_sessionsession_id, title, note给 session 记标题和说明
search_worksquery, limit在 title / goal / prompt / last_message 里找子串，从新到旧
check_for_updateforce问 registry 有没有新版本
cancel_codex_workertask_id终止 worker。跨进程按 pid 兜底，先确认那个 pid 跑的是 codex

必填的两个：ownedPaths（派单前和在跑的 worker 求交集，重叠就拒，只在派单时查）和 goal.objective（worker 会建成 Codex 原生 goal）。session_id 不传就归不了组，一批活传同一个值。

和 Claude Code 的 subagent 有什么区别

文件隔离不是差别：subagent 自己也能开 worktree。差别在模型和进程。

Claude Code subagentcodex-supervisor worker
能跑什么模型只能选 Claudemodel 透传给 Codex CLI，DeepSeek 也能挂
干活的是谁Claude Code 自己独立的 codex exec 进程
两路写同一个文件靠 worktree 隔开，没有路径声明派单前查 ownedPaths 交集，重叠直接拒
主线程进程挂了worker 一起没thread_id 在 sqlite 里，resume_codex_worker 接回同一个会话
谁能驱动只有 Claude Code任何 MCP 客户端
看过程只有它返回的结论原始 JSONL 和网页看板

状态机

status含义
queued已派单，未启动
running运行中。phase：starting → thinking → command → editing → reporting
completed成功
failed非零退出码、turn.failed、spawn 失败
cancelled被 cancel_codex_worker 中断
lost被外部信号杀掉、MCP 进程消失、或者行写了但进程从没起来。resume_codex_worker 接回

终态分两步落盘：turn.completed 先把 status 置成 completed，进程退出后才写 exit_code；wait_codex_workers 等到 exit_code 落了才返回。Windows 没有信号，外部 kill 只报 failed 加退出码。Codex 原生 goal 的 paused / blocked 算 running 并进 needs_attention，usageLimited / budgetLimited 算 failed。

状态存储

默认在 ~/.codex-supervisor/：

文件内容
data/supervisor.sqlitetasks（一行一个 work）、task_events、sessions、side_sessions / side_turns（旁问）
data/runs/<taskId>.jsonlCodex --json 的原始输出
data/update-check.json、auto-update.json更新检查和后台更新的记录
worktrees/<taskId>/该 worker 的 Git worktree

changed_files 按 worktree 的真实 diff 算，worker 用 shell 改的、自己 commit 过的都能看到。中文文件名原样返回。老版本的库第一次打开自动迁移。

环境变量

变量默认作用
SUPERVISOR_HOME~/.codex-supervisor状态根目录。MCP 和看板要指同一个
CODEX_HOME~/.codex只读，读 Codex 原生的 goals_1.sqlite 和 MCP 配置
CODEX_BINcodexCodex CLI 路径。Windows 上 .cmd shim 自动绕开
GIT_BINgitGit 路径
SUPERVISOR_WEB_PORT / SUPERVISOR_WEB_HOST7877 / 127.0.0.1看板监听地址
CODEX_SUPERVISOR_NO_UPDATE_CHECK未设1 关闭更新检查
CODEX_SUPERVISOR_REGISTRYhttps://registry.npmjs.org更新检查和自动更新用的 registry
CODEX_SUPERVISOR_UPDATE_TIMEOUT_MS4000等 registry 的上限
CODEX_SUPERVISOR_NO_AUTO_UPDATE未设1 关闭后台自动更新（只提醒）
CODEX_SUPERVISOR_SKIP_SKILL_SYNC未设1 关闭 server 启动时的 skill 同步
CODEX_SUPERVISOR_SKIP_SETUP未设1 跳过 postinstall 的自动安装
CODEX_SUPERVISOR_NPM未设自动更新用的 npm，默认用当前 node 自带的

GUI 客户端（Claude Desktop、Cursor、Windsurf）不跑 postinstall，自己把这段加进它的 MCP 配置文件，PATH 里常常没有 codex，显式给 CODEX_BIN：

json
{  "mcpServers": {    "codex-supervisor": {      "command": "npx",      "args": ["-y", "codex-supervisor-mcp"],      "env": { "CODEX_BIN": "/usr/local/bin/codex" }    }  }}

更新

不用手动更。server 启动时后台查一次 registry，有新版就起独立进程 npm i -g 到同一个全局路径；正在跑的会话不受影响，下一个新会话就是新版。只对 npm i -g 装的那份生效，git 源码和 npx 起的不碰。skill 也一样，每次启动刷到已有的 skill 目录，改过的先备份成 SKILL.md.bak-<时间戳>。

装失败（全局目录要 sudo）时 update 字段带原因，手动 npm install -g codex-supervisor-mcp@latest。0.6.1 及以前只提醒不自动装，手动升一次就进自动了。换了 Node 版本注册的路径会失效，claude mcp remove -s user codex-supervisor、codex mcp remove codex-supervisor 后重装。重跑安装：codex-supervisor-setup（--skill-only / --mcp-only / --dry-run）。

卸载：

bash
npm uninstall -g codex-supervisor-mcpclaude mcp remove -s user codex-supervisorcodex mcp remove codex-supervisorrm -rf ~/.claude/skills/codex-supervisor ~/.agents/skills/codex-supervisor ~/.codex/skills/codex-supervisor ~/.codex-supervisor

Windows

  • npm 装的 CLI 是 codex.cmd，Node 拒绝直接 spawn 它。这里绕到 node_modules/@openai/codex/bin/codex.js 用 node 起，不用 shell: true，那样取消时只杀得掉 shell。
  • 跨进程取消用 taskkill /PID <pid> /T /F 杀整棵树，先确认那个 pid 跑的是 codex。
  • 除 PATH 外还探 %APPDATA%\npm、%LOCALAPPDATA%\pnpm、%LOCALAPPDATA%\Volta\bin、%ProgramFiles%\nodejs。

排查

症状原因处理
claude mcp list 里没有装法不跑 postinstallcodex-supervisor-setup 或手动 claude mcp add
派单报 codex only resolved to a shell shimWindows 只找到 .cmd，背后的包入口没了重装 @openai/codex，或 CODEX_BIN 指到 codex.js
worker 一起来就 failed，spawn codex ENOENT进程 PATH 里没有 codex配置里设 CODEX_BIN
Cannot find module 'node:sqlite'Node 低于 22.13.0升 Node
worker lostMCP 进程被杀，worker 跟着没了resume_codex_worker 接回
worker 说 git add 报 index.lock: Operation not permitted默认沙箱把 .git 设成只读收活时 land_codex_worker 带 commitMessage，或派单用 danger-full-access
ownedPaths overlap with active worker(s)两路认领了同一片路径改拆法，或先取消占着的那路
看板打开是空的看板和 MCP 的 SUPERVISOR_HOME 不是同一个在配了 .mcp.json 的项目目录里起，或显式传同一个 SUPERVISOR_HOME
port 7877 ... is already in use已经有一个看板在跑直接开它，或 SUPERVISOR_WEB_PORT=8080 再起一个

已知限制

  • worker 是 MCP 进程的子进程。MCP 被 kill，worker 跟着没了，结算成 lost；worktree 和 thread_id 都在，resume_codex_worker 接回。让它不跟着死要常驻 daemon，在 Roadmap 里。
  • 默认 workspace-write 沙箱里 worker 提交不了（Codex 把 .git 设成只读）。要么收活时 land_codex_worker 带 commitMessage 替它提交，要么派单用 danger-full-access。
  • worktree 从一个提交切，你工作区里没 commit 的东西不在里面。
  • 只隔离工作目录。临时目录、数据库、端口是共用的。
  • ownedPaths 只在派单时查，拦不住 worker 新建清单外的文件。收活看 diff。
  • 只管「跑完了」不管「对不对」，验收得主线程自己做。
  • 一次 wait_codex_workers 等不到底，客户端的 MCP 工具超时是硬墙，靠反复调。
  • search_works 是子串匹配，几百条够用。

Roadmap

做完的：CODEX_BIN / SUPERVISOR_HOME / GIT_BIN；status 和 phase 拆开；ownedPaths / goal / dependsOn；thread_id 落库 + resume_codex_worker；并发和多进程写库；session_id、search_works、原生 goal；Windows；网页看板；baseRef；收活三件套 get_worker_diff / ask_codex_worker / land_codex_worker；后台自动更新。

下一个：常驻 daemon，派单和进程生命周期从 MCP 进程里拿出来。

不做的：向量检索（子串匹配在这个规模更快、零维护）、usage_count 排序（实测 80 个 work 里只有 2 个被回头引用过）。

开发

bash
npm installnpm test               # fake-codex 回放，快且确定npm run test:edge      # 只跑 test/edgenpm run test:real      # 真 codex CLI 端到端npm run web:dev        # 看板开发，/api 代理到 7877npm run web:build      # 打包到 web/dist，发 npm 前自动跑

CI 跑 Ubuntu / macOS / Windows，另加一个 Node 22.13.0 的 job 卡 engines 下界。

参与贡献

看 CONTRIBUTING.md。安全问题走 私密通道，见 SECURITY.md。

License

MIT

Source: README.md at commit efbd4a8

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.7.3LatestOct 7, 2026