zriyox/codex-supervisor-mcp

Codex MCP server: run parallel Codex CLI workers in isolated git worktrees, state on disk, web dashboard, auto-update.

About codex-supervisor-mcp

官网 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，附一个网页看板。

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

问题 做法 ------ 几个 worker 互相踩文件 一个 worker 一个 Git worktree，ownedPaths 在派单前查冲突 worker 的过程塞爆主线程上下文 事件写 data/runs/.jsonl，读的时候有 limit / maxChars / kinds 三道闸 主线程读一次状态就顶满 getorchestrationoverview 把全部 worker 压进 7000 字节 进程重启后不知道谁还在跑 supervisor.sqlite 一行一个 work，带 threadid 换个会话接不上之前的 worker resumecodexworker 走 codex exec resume ，接的是同一个 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 都行。

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

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

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

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

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

From the project README.

Maintaining this server?

Add the radar badge to your README — it shows your project was picked up by MCP Radar and links to this page:

[![On MCP Radar](https://mcp.liqiwa.com/badge.svg)](https://mcp.liqiwa.com/s/zriyox--codex-supervisor-mcp.html)

Related MCP servers