Codex Supervisor MCP

Name: Codex Supervisor MCP
Author: zriyox

作者：zriyox版本 0.8.0i★ –i在你的电脑上运行

注册名称io.github.zriyox/codex-supervisor-mcp

安装

概览

作者提供的说明（英文原文）

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

PopNx MCP 的三大支柱

这三项永远不会合并成一个分数：意见、测量和人气是不同的东西。

用户评价i暂无评价评价功能将在后续阶段与账户功能一起开放
我们的基础检查i1 项中通过 1 项依据公开信息检查；尚未扫描代码
使用情况i尚未统计★ –

它能帮你做什么

我们还没有为它写通俗的介绍。下面是我们从注册中心读取到的事实。

连接方式: 在你的电脑上运行
传输方式: stdio
分类: 数据库与数据集

安装

选择你使用的 AI 应用，然后复制设置。

安装之前

基础检查：1 项中通过 1 项
在你的电脑上运行，拥有你的用户账户的权限（文件、网络、应用）。
需要你自己填写： CODEX_BIN, SUPERVISOR_HOME

你需要

npm已安装 Node.js（用于 npx 命令）

你用的是哪个应用？

ClaudeClaude CodeCursorVS CodeChatGPT

在上方选择你的应用。我们会记住它，下次按钮会显示“安装到 …”。

打开 Claude Desktop → Settings → Developer → Edit Config，把下面的内容粘贴到 claude_desktop_config.json

{
  "mcpServers": {
    "codex-supervisor": {
      "command": "npx",
      "args": [
        "-y",
        "codex-supervisor-mcp"
      ],
      "env": {
        "CODEX_BIN": "your-value",
        "SUPERVISOR_HOME": "your-value"
      }
    }
  }
}

在终端中运行这条命令

claude mcp add codex-supervisor --env CODEX_BIN=your-value --env SUPERVISOR_HOME=your-value -- npx -y codex-supervisor-mcp

运行前请先填写空着的值。

在 Cursor 中打开

或者自己复制设置

粘贴到项目中的 .cursor/mcp.json，或 ~/.cursor/mcp.json

{
  "mcpServers": {
    "codex-supervisor": {
      "command": "npx",
      "args": [
        "-y",
        "codex-supervisor-mcp"
      ],
      "env": {
        "CODEX_BIN": "your-value",
        "SUPERVISOR_HOME": "your-value"
      }
    }
  }
}

浏览器会先询问是否打开应用，然后应用会显示设置并请你确认。密钥的值会留空，由你自己填写。

在 VS Code 中打开

或者自己复制设置

粘贴到项目中的 .vscode/mcp.json

{
  "servers": {
    "codex-supervisor": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "codex-supervisor-mcp"
      ],
      "env": {
        "CODEX_BIN": "your-value",
        "SUPERVISOR_HOME": "your-value"
      }
    }
  }
}

浏览器会先询问是否打开应用，然后应用会显示设置并请你确认。密钥的值会留空，由你自己填写。

这个服务器在你的电脑上运行，而 ChatGPT 只能连接互联网上的服务器。请选择其他应用。

你的选择通过 Cookie 保存在这台设备上，无需账户。

需要你填写的值

CODEX_BIN env
Path to the codex CLI when it is not on PATH
SUPERVISOR_HOME env
State directory, default ~/.codex-supervisor

这些设置是根据作者在注册中心的条目生成的。如果 README 的写法不同，请以 README 为准。

它能做什么

它在你的电脑上运行；安装后，工具列表会显示在你的 AI 应用中。

基础检查i

我们检查的是任何人都能看到的信息；我们没有阅读代码。不适用的检查项不计入总数。 · 检查于 2026年11月7日

✓ 通过
作者与仓库一致
注册名称已通过 GitHub 账户 zriyox 验证，该账户拥有此仓库
… 尚未检查
仍在维护
我们还没有从 GitHub 读取这个仓库
… 尚未检查
有许可证
我们还没有从 GitHub 读取这个仓库
– 不适用
端点有响应
它在你的电脑上运行，没有互联网端点
– 不适用
使用 OAuth 登录
在你的电脑上运行，改用本地设置
… 尚未检查
工具描述中没有隐藏指令
它在你的电脑上运行；我们只能读取互联网端点的工具列表

与“数据库与数据集”中的其他服务器比较i

星标数多于此分类中其他 952 个服务器的 0%
发布到注册中心的时间比此分类中其他 952 个服务器的 66% 更新
基础检查结果等于或优于此分类中其他 952 个服务器的 100%

与注册中心里这个分类中所有活跃的服务器比较。只有当发布者拥有该仓库时，星标数才计入。

常见问题

Codex Supervisor MCP 安全吗？

它在 1 项适用的基础检查中通过了 1 项。我们没有阅读代码。在添加密钥或令牌之前，请先看看这个服务器要求哪些权限，并使用只具备所需权限的密钥。

它需要哪些密钥或代码？

注册中心没有列出必需的密钥，不过有些服务器会在首次使用时要求你登录。

它在我的电脑上运行还是在云端？

它在你的电脑上运行。你的 AI 应用会在需要时启动它，数据不会经过作者的服务器（除非它自己调用在线服务）。

它还在维护吗？

GitHub 仓库最后更新于–，最新版本（0.8.0）于29天前进入注册中心。

哪些应用可以使用它？

支持 MCP 的应用，例如 Claude Desktop、Claude Code、Cursor 和 VS Code。你的电脑上还需要有 Node.js。

有什么可以替代它？

同一分类中有：Supabase, MongoDB MCP Server, Elasticsearch MCP Server

替代选择

同一分类中其他作者的服务器，按星标数排序。

如何看卡片：★ GitHub 星标i三大支柱：评价 · 检查 · 使用情况i更新 = 最新版本发布到注册中心的时间i

Supabase

作者：supabase

MCP server for interacting with the Supabase platform

电脑或云端★ 2,993Apache-2.0今天更新

安装

MongoDB MCP Server

作者：mongodb-js

MongoDB Model Context Protocol Server

在你的电脑上运行★ 1,157Apache-2.0前天更新

安装

Elasticsearch MCP Server

作者：cr7258

MCP server for interacting with Elasticsearch

在你的电脑上运行★ 315Apache-2.014个月前更新

安装

作者的 README

打开 README

按原文从作者的仓库复制。PopNx MCP 没有审查或背书其内容。HTML、图片和脚本已被移除。链接会离开本站。

codex-supervisor-mcp

English | 中文

官网 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 秒真跑：create_codex_worker ×3，三个 worker 各自 worktree 并行，主线程收 3 份 diff 合成一次 commit。*

解决什么

问题	做法
几个 worker 互相踩文件	一个 worker 一个 Git worktree，`ownedPaths` 在派单前查冲突
worker 不是只会改代码	四种 `workspaceKind`：Git 编辑 `git_worktree`、只读 `read_only_in_place`、联网研究 `scratch`、显式授权的非 Git 写入 `in_place_write`；非 Git 默认绝不写原目录
worker 的过程塞爆主线程上下文	事件写 `data/runs/ .jsonl`，读的时候有 `limit` / `maxChars` / `kinds` 三道闸
主线程读一次状态就顶满	`get_orchestration_overview` 把全部 worker 压进 7000 字节
进程重启后不知道谁还在跑	`supervisor.sqlite` 一行一个 work，带 `thread_id`
换个会话接不上之前的 worker	`resume_codex_worker` 走 `codex exec resume` ，接的是同一个 Codex 会话
分不清「跑失败」和「进程没了」	状态机把 `failed` 和 `lost` 分开
分不清是谁报错	status / overview / overview_delta 带 `failure.source` 和 `failure.code`，区分 provider、supervisor_process、workspace_setup、model_output、acceptance、worker_process
worker 说做完了其实没有	派单给 `acceptance` 验收命令，worker 退出后 supervisor 在它的 worktree 里跑，失败 `land` 拒绝
看不见一批活现在到哪了	`codex-supervisor-web` 开一个看板，按 session 看每路 worker 在干什么
改动留在本地没上线	收活默认 `land_codex_worker` 合回主分支；主线程自己的改动必须 commit + push；部署前用远端 SHA 核对文件真的在线上
worktree / 分支越堆越多	`verify_delivery_push` 后自动生成 cleanup plan；只对 `acceptance passed + push_verified + clean` 判 SAFE，主线程显式 `apply_cleanup` 才删 worktree，branch/证据永远保留

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

五分钟跑起来

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

1. 装

npm install -g codex-supervisor-mcp

npm 全局安装在允许执行安装脚本时，会运行 postinstall，给检测到的 Claude Code/Codex 装 skill 并注册 MCP。--ignore-scripts、禁用安装脚本或只运行 npx 不保证自动注册；没看到时先运行 codex-supervisor-setup，再查两端 mcp get。手动注册也可以：

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 叫「补单测」。

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

preflight_codex_worker  同 workspace/base/sandbox/guard 先跑必要 probe

get_worker_preflight 确认 passed；contract 变化就重跑 create_codex_worker ×3 每路带 preflight_id、session_id、ownedPaths、goal wait_codex_workers 默认等 60 秒，到点返回快照，没完就接着等 get_worker_result ×3 收每路的汇报，带它真跑过的命令和退出码 get_worker_diff ×3 看实际改动；证据对得上再决定是否 land

每路的改动在各自的 codex/ 分支上。验收和 diff 都过了，主线程用 land_codex_worker 带 commitMessage 合入；worker 不自行提交。

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 改。看板只看，不派单不取消。

长门禁脚本可主动上报阶段：

node "$CODEX_SUPERVISOR_STAGE_CLI" "gate:s3" --detail "integration queue"

current_stage 会出现在 status / overview / wait，终态保留为 last_stage；不要放 token、密码或 DSN。

我自己怎么用

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

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

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

【角色】   你是主脑：读文档和代码，派 worker，核结果，更新文档，向我汇报。不写业务代码。

派活和盯进度用 codex-supervisor 这个 skill，开工前先加载它。【背景】这一块为什么做，上一块留下了什么【先读】哪几份文档的哪几节。几份说法不一样时以哪份为准【仓和分支】工作目录在哪，各分支现在在哪个提交，哪些分支只读【做什么】照任务书第几节那张表做。按能独立验收的功能包拆，表里没有的不做。worker 不自行 commit 【派活】先 search_works 看有没有派过，别重复整批用同一个 session_id 改同一批文件就串行，写入范围不重叠才并行。ownedPaths 覆盖实现、测试、路由、DI、配置和迁移依赖先写 workspaceSetup；写 worker 先过同 contract 的 preflight task 写全：背景、文档出处、完整写集、验证命令、输出格式验证命令同时填 acceptance；worker 用 CODEX_SUPERVISOR_ACCEPTANCE_CLI 自查 worker 交回来先看 diff。它说过了不算，你看到才算【构建和测试】全走远端机器，本机不跑【红线】不改什么，不推什么，不读什么【必须停下来问我】【汇报】中文，表格优先，报哪几项，然后停下来等我

主脑一轮下来调的工具：

search_works            查这批活派过没有

preflight_codex_worker 同环境跑 probe，确认 sandbox / guard / base / cache 真可用 get_worker_preflight 核 probe 的实际 command evidence；passed 才能派目标 worker create_codex_worker 一个功能包一个 worker，同一个 session_id，ownedPaths 不重叠 wait_codex_workers 60 秒一轮，compact: true，没完接着调 get_worker_result 它说自己做了什么，verification 里是它真跑过的命令 get_worker_diff 它实际做了什么 ask_codex_worker 对不上就问它为什么，只读，不动它的线程 resume_codex_worker 要改就继续同一线程；主线走远了带 rebaseOnto land_codex_worker 核过了，带 commitMessage 代提交并落进集成分支

功能包在 land 前仍可 resume_codex_worker 继续修改。真正需要拆开的原因是写集冲突、依赖顺序或独立验收，不是“每一步都必须换一个模型线程”。

看板里有什么

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

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

工具

39 个。

工具	入参	作用
`check_workers`	无参	返回新终态、故障及长线程交接提醒；同一 run 的 handoff 只提醒一次，不中止或复制活跃 worker。已死的第1轮 `lost` / `no_work` / `invalid_report` 最多恢复一次；用宿主定时调用及独立 CODEX_SUPERVISOR_OBSERVER_ID 接回
`overview_delta`	`cursor`	主线程默认轮询入口：只返回 active / needs_attention / ready_to_land / ready_to_clean、cursor 后变化、短版 attention_reason / next_action 和 next_cursor；不返回全量历史、prompt、diff、event 或 worker capsule
`check_acceptance`	`cwd`, `acceptance`, `baseRef`, `timeoutMs`	派单前实际运行给定验收命令，不建 worker，不证明 worker 完成；数量 grep 会提示不能证明失败名单和必跑执行
`preflight_codex_worker`	`cwd`, `workspaceKind`, `inPlaceAuthorization`, `workspaceSetup`, `ownedPaths`, `probeCommands`, `baseRef`, `sandbox`, `allowedCommands`, `context`, `contracts`, `networkAccess`, `writableRoots`	用与目标 worker 相同的 workspace/base/sandbox/guard 起短 probe worker；它必须实际跑完每条 probe command。probe 自动获得本次 guard-only 允许，但不进入目标 worker contract；联网和凭据目录仍须显式授权
`get_worker_preflight`	`task_id`	返回 probe 的实际 command evidence、运行环境 contract hash、worker outcome 和 `running/passed/failed`；probe 全部执行通过时，报告 JSON 错误或已 exit 0 的 close-handler 缺失只留诊断，不误判环境失败
`create_codex_worker`	`task`, `cwd`, `workspaceKind`, `inPlaceAuthorization`, `workspaceSetup`, `ownedPaths`, `goal`, `preflight_id`, `forbid`, `allowedCommands`, `context`, `contracts`, `externalOutputs`, `networkAccess`, `writableRoots`, `maxRunMs`, `maxTotalMs`, `acceptance`, `session_id`, `session_title`, `session_note`, `dependsOn`, `baseRef`, `sandbox`, `model`, `reasoningEffort`, `title`, `skipGitRepoCheck`	Git 默认隔离 worktree；非 Git 写入必须选 `scratch` 或有授权、paths、acceptance 的 `in_place_write`。`workspaceSetup` 在起 worker 前链接依赖、初始化子模块、跑 prepare；`preflight_id` 给了就必须是通过的同环境 probe
`create_codex_followup_worker`	`task_id`, `followup_prompt`, `session_id`, `session_title`, `title`, `cwd`, `sandbox`, `model`, `ownedPaths`, `forbid`, `allowedCommands`, `context`, `contracts`, `externalOutputs`, `networkAccess`, `writableRoots`, `workspaceKind`, `workspaceSetup`, `goal`, `baseRef`, `acceptance`	新会话继承父任务上下文：未 land 用父分支当前提交，已 land 用当前集成 HEAD，显式 `baseRef` 优先。未提交父改动不复制；不支持 `preflight_id`、`dependsOn`、`skipGitRepoCheck`
`resume_codex_worker`	`task_id`, `prompt`, `rebaseOnto`, `acceptance`, `context`	接同一个 Codex 会话继续跑，`thread_id` 不变。原生 goal 仍 active 或 goal 状态库不可判定时，本轮自动省略 output schema，避免 `ActiveTurnOutputSchemaMismatch`。`rebaseOnto` 先把 worktree 挪到主线新头（stash、跳过已合入补丁、重放新增提交、放回），冲突原样退回不起 worker
`wait_codex_workers`	`task_ids`, `mode`(any/all), `timeoutMinutes`, `timeoutMs`, `allowLongWait`, `compact`, `emitProgress`, `includeEvents`, `eventLimit`, `eventMaxChars`, `eventKinds`	等终态，单次预算默认最多 60 秒，只有确认宿主超时允许后才传 `allowLongWait: true`。返回实际/请求预算与 `timeout_capped`，`termination_reason` 区分 settled / budget_exhausted / client_cancelled；`emitProgress` 可选，每路摘要用 `compact`
`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` 是主线走了多远（`contains_base: false` 时 `behind` 为 `null`，那是换了线）
`get_worker_diff`	`task_id`, `file`, `hunk`, `pageSize`, `cursor`, `maxChars`, `paths`	worker 实际改了什么。默认完整文件索引与 hunk 数；按 `file` + `hunk`/`cursor` 分页读 patch。显式 `maxChars` 且不传 `file` 保留旧整份限流模式
`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`, `includeFollowupParents`, `commitMessages`, `ignoreAcceptance`, `allowOutsideOwned`	把 worker 在 `codex/` 上的提交 cherry-pick 到派单目录的当前分支。目标要干净，冲突回滚，验收 `failed` 拒绝；报告格式错不再单独阻止显式 land。`commitMessage` 先替当前 worker 把未提交改动提交成一笔；`includeFollowupParents` 按 root-first 落地整条 followup 链，`commitMessages` 给链中各路提供各自的 checkpoint 提交说明
`verify_delivery_push`	`task_id`, `remote`, `branch`	fetch 指定 remote branch 并证明 `landed_head` 已可达；只读验证，不会 push 或部署。通过后记录 `push_verified` 并生成 cleanup plan
`cleanup_plan`	`task_ids`, `project_root`	生成 15 分钟有效的 SAFE / REVIEW / BLOCKED 计划，含原因、fingerprint 与回收空间估算；SAFE 必须 acceptance passed、push verified、干净且无活跃依赖/进程
`apply_cleanup`	`plan_id`, `item_ids`	只在未过期计划上二次校验 SAFE item、重新 fetch remote 并确认 landed SHA 仍可达后执行 `git worktree remove/prune`；保留 branch、task、events、JSONL、artifacts
`cleanup_history`	`task_id`, `limit`	查询 cleanup 的计划、理由、fingerprint 和实际回收记录
`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_context_snapshot_meta`	`task_id`	只读 worker context 的 snapshot ID、fact IDs、token 估算和排除项；不返回 capsule 正文或历史记录
`get_fact`	`fact_id`	按 ID 审计原始 fact 版本及 `effective_state`；撤销和自动过期均保留原版本
`search_worker_facts`	`task_id`, `query`, `limit`, `cursor`	只检索当前 work、显式依赖和路径命中 repo scope 的 verified facts；返回 coverage / next_cursor，不返回 raw history
`get_worker_evidence`	`task_id`, `limit`	返回某 worker 的有界 event 元数据和 retained artifact 索引；按需再点查 artifact / event
`get_artifact`	`artifact_id`, `maxChars`	读取一个 supervisor-managed evidence artifact；不影响 worker capsule 或主线程自动上下文
`promote_worker_fact`	`fact_id`, `scope`, `watchedPaths`, `expiresAt`	主线程显式把 candidate 追加为 verified fact；repo scope 必须声明 watchedPaths，worker 不能自升真相
`revoke_worker_fact`	`fact_id`, `reason`	主线程审计后追加撤销版本和事件，不覆盖原 fact；被撤销事实从 search / capsule 排除

| create_independent_verifier | task_id, title | 为已结算 worker 创建独立 read-only / 无网络 verifier；只给

只显示了开头部分；其余内容请在仓库中阅读