Skip to main content
Glama
zriyox

codex-supervisor-mcp

by zriyox
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

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

换个会话接不上之前的 worker

resume_codex_worker 走 codex exec resume <thread_id>，接的是同一个 Codex 会话

分不清「跑失败」和「进程没了」

状态机把 failed 和 lost 分开

worker 说做完了其实没有

派单给 acceptance 验收命令，worker 退出后 supervisor 在它的 worktree 里跑，失败 land 拒绝

看不见一批活现在到哪了

codex-supervisor-web 开一个看板，按 session 看每路 worker 在干什么

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

Related MCP server: deepseek_harness

五分钟跑起来

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

1. 装

npm install -g codex-supervisor-mcp

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

claude mcp add -s user codex-supervisor -- npx -y codex-supervisor-mcp
codex 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、goal
wait_codex_workers       默认等 2 分钟，到点返回快照，没完就接着等
get_worker_result ×3     收每路的汇报，带它真跑过的命令和退出码

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

3. 开看板

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 接上。结构固定：

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

主脑一轮下来调的工具：

search_works            查这批活派过没有
create_codex_worker     一步一个 worker，同一个 session_id，ownedPaths 不重叠
wait_codex_workers      2 分钟一轮，compact: true，没完接着调
get_worker_result       它说自己做了什么，verification 里是它真跑过的命令
get_worker_diff         它实际做了什么
ask_codex_worker        对不上就问它为什么，只读，不动它的线程
resume_codex_worker     要改就追一条，让它 amend 进原来那个提交；主线走远了带 rebaseOnto
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_worker

task, cwd, ownedPaths, goal, acceptance, session_id, session_title, session_note, dependsOn, baseRef, sandbox, model, reasoningEffort, title, skipGitRepoCheck

起一个 worker。acceptance 是验收命令，worker 退出后 supervisor 在它的 worktree 里跑，退出码 0 算过。baseRef 指定 worktree 从哪个提交切，默认 HEAD，接另一路填它的 codex/<id>

create_codex_followup_worker

task_id, followup_prompt, session_id, 其余同上

开一个新会话，把老 worker 的 prompt、状态、近期事件拼进去

resume_codex_worker

task_id, prompt, rebaseOnto, acceptance

接同一个 Codex 会话继续跑，thread_id 不变。rebaseOnto 先把 worktree 挪到主线新头（stash、重放它自己的提交、放回），冲突原样退回不起 worker

wait_codex_workers

task_ids, mode(any/all), timeoutMinutes, timeoutMs, compact, includeEvents, eventLimit, eventMaxChars, eventKinds

等终态。默认 2 分钟，到点带快照返回，worker 照跑；compact 每路只回一行，带 idle_seconds / command_running，分得清长命令和卡住

get_orchestration_overview

status, limit

全部 worker 的状态表，封顶 7000 字节。带 version 和 update

get_worker_result

task_id, limit, maxChars, includeFiles

worker 自己的汇报，默认截 6000 字节、truncated 提示读全。acceptance 是 supervisor 替你跑的验收过没过，verification 是它自己跑过的命令和退出码，base_behind 是主线走了多远

get_worker_diff

task_id, maxChars, paths

worker 实际改了什么：从 worktree 起点到工作区的 patch，提交没提交都算。maxChars 管总量，超了的文件只列名

ask_codex_worker

task_id, question, timeoutMs, maxChars, fresh, end

旁路问 worker 一句。线程 fork 成只读侧会话，没网络、没 MCP 工具，worker 本身不动。worker 被 resume 过会自动换新 fork，fresh 强制换，end 删

land_codex_worker

task_id, onto, commitMessage, ignoreAcceptance

把 worker 在 codex/<id> 上的提交 cherry-pick 到派单目录的当前分支。目标要干净，冲突回滚，验收 failed 拒绝。commitMessage 先替它把未提交的改动提交成一笔，ignoreAcceptance 放行

get_worker_summary

task_id

一段话：goal、状态、改动、最后一条命令和消息

get_codex_worker_status

task_id, includePrompt, promptMaxChars

单个 worker 的状态细节

get_codex_worker_events

task_id, limit, maxChars, kinds

原始事件流

get_worker_goal

task_id

派单时记的 goal + Codex 原生 goal（token、用时）

list_codex_workers

status, includeHistory, includeDetails

列 worker，默认只看在跑的

get_session_works

session_id

一个 session 的全部 worker。主线程重启后靠它找回那批活

describe_session

session_id, title, note

给 session 记标题和说明

search_works

query, limit

在 title / goal / prompt / last_message 里找子串，从新到旧

check_for_update

force

问 registry 有没有新版本

cancel_codex_worker

task_id

终止 worker。跨进程按 pid 兜底，先确认那个 pid 跑的是 codex

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

和 Claude Code 的 subagent 有什么区别

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

Claude Code subagent

codex-supervisor worker

能跑什么模型

只能选 Claude

model 透传给 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.sqlite

tasks（一行一个 work）、task_events、sessions、side_sessions / side_turns（旁问）

data/runs/<taskId>.jsonl

Codex --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_BIN

codex

Codex CLI 路径。Windows 上 .cmd shim 自动绕开

GIT_BIN

git

Git 路径

SUPERVISOR_WEB_PORT / SUPERVISOR_WEB_HOST

7877 / 127.0.0.1

看板监听地址

CODEX_SUPERVISOR_NO_UPDATE_CHECK

未设

1 关闭更新检查

CODEX_SUPERVISOR_REGISTRY

https://registry.npmjs.org

更新检查和自动更新用的 registry

CODEX_SUPERVISOR_UPDATE_TIMEOUT_MS

4000

等 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：

{
  "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）。

卸载：

npm uninstall -g codex-supervisor-mcp
claude mcp remove -s user codex-supervisor
codex mcp remove codex-supervisor
rm -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 里没有

装法不跑 postinstall

codex-supervisor-setup 或手动 claude mcp add

派单报 codex only resolved to a shell shim

Windows 只找到 .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 lost

MCP 进程被杀，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。

  • 验收是 acceptance 里写了什么就查什么。没写的事它不会替你查，verification 只是 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 个被回头引用过）。

开发

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

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

参与贡献

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

License

MIT

This server cannot be deployed

Context Every Agent Can ShareAgents share what they learn, hand off work, and keep it when you switch models. Start with 5 GB free.fulcradynamics.comAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • agent-bridge

    suneel944
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables coordinating Claude Code and Codex across separate Git worktrees with shared issue ownership, file reservations, messages, and explicit handoffs.
    1,876 PyPI
    4
    MIT

  • deepseek_harness

    XiangyunHu
    A
    license
    A
    quality
    B
    maintenance
    A task-level STDIO MCP server that lets Codex or any other MCP client hand off scoped coding jobs to an asynchronous worker agent which reads the code, edits files, and runs tests, while the client keeps ownership of planning and acceptance. Exposes submit, wait, query, follow-up, and cancel tools so multiple clients can queue and monitor tasks against a chosen project root.
    5
    1
    MIT

  • pi-mcp

    lucasjingcn
    A
    license
    Not graded
    quality
    B
    maintenance
    Orchestrates multiple coding agents at once so an MCP client can delegate implementation work while retaining judgment: each agent runs in its own isolated git worktree and branch, claims the files it edits, and communicates via a mailbox and shared board. Supports blocking questions to the orchestrator, Codex-written acceptance tests locked before workers start, scope validation, and reporting on first-pass success.
    Apache 2.0

  • Antigravity MCP Bridge

    Daniiislo
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables Codex or Claude Code to orchestrate persistent Antigravity CLI workers as independent implementers and testers within restricted workspace roots. It supports asynchronous task dispatch, progress polling, result inspection, follow-up messages, and cancellation with bounded, audited local event logging.
    840 npm
    3
    MIT