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の3つの柱

この3つを1つのスコアにまとめることはしません。意見、測定、人気はそれぞれ別のものだからです。

利用者の声iレビューはまだありませんレビューは今後のステップで、アカウント機能と一緒に始まります
私たちの基本チェックi1項目中1項目に合格公開情報からチェック。コードはまだスキャンしていません
利用状況i未計測★ –

できること

このサーバーのやさしい解説はまだ書いていません。以下はレジストリから読み取った事実です。

接続方法: パソコンで動く
トランスポート: stdio
カテゴリ: データベース・データセット

インストール

使っているAIアプリを選んで、設定をコピーしてください。

インストールの前に

基本チェック：1項目中1項目に合格
あなたのパソコンで、あなたのユーザーと同じ権限（ファイル、ネットワーク、アプリ）で動きます。
自分で入力するもの： CODEX_BIN, SUPERVISOR_HOME

必要なもの

npmNode.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月6日にチェック

✓ 合格
作者とリポジトリが一致
レジストリ名は、リポジトリを所有するGitHubアカウント zriyox で確認済みです
… 未チェック
今もメンテナンスされている
このリポジトリはまだGitHubから読み取っていません
… 未チェック
ライセンスがある
このリポジトリはまだGitHubから読み取っていません
– 対象外
エンドポイントが応答する
これはパソコンで動くため、インターネット上のエンドポイントはありません
– 対象外
OAuthでサインイン
パソコンで動き、代わりにローカルの設定を使います
… 未チェック
ツールの説明に隠れた指示がない
パソコンで動くサーバーです。ツール一覧を読み取れるのは、インターネット上のエンドポイントがある場合だけです

データベース・データセットのほかのサーバーとの比較i

このカテゴリのほかの953件のうち0%よりスターが多い
このカテゴリのほかの953件のうち66%より最近レジストリに公開
基本チェックの結果が、このカテゴリのほかの953件のうち100%と同じかそれ以上

レジストリでこのカテゴリにある有効なすべてのサーバーと比較しています。スターは、公開者がリポジトリの所有者である場合だけ数えます。

よくある質問

Codex Supervisor MCPは安全ですか？

当てはまる基本チェック1項目のうち1項目に合格しました。コードは読んでいません。キーやトークンを追加する前に、サーバーがどんなアクセスを求めているかを確認し、必要な権限だけを持つキーを使ってください。

どんなキーやコードが必要ですか？

レジストリには必須のキーは載っていません。ただし、最初に使うときにサインインを求めるサーバーもあります。

パソコンで動きますか、それともクラウドですか？

あなたのパソコンで動きます。必要なときにAIアプリが起動し、データは作者のサーバーを通りません（サーバー自体がオンラインサービスを呼び出す場合を除きます）。

今もメンテナンスされていますか？

GitHubリポジトリの最終更新は–、最新バージョン（0.8.0）がレジストリに届いたのは29 日前です。

どのアプリで使えますか？

Claude Desktop、Claude Code、Cursor、VS CodeなどのMCP対応アプリで使えます。パソコンにNode.jsも必要です。

代わりに使えるものは？

同じカテゴリには：Supabase, MongoDB MCP Server, Elasticsearch MCP Server

代わりの候補

同じカテゴリで、ほかの作者が作ったサーバー。スターの多い順。

カードの見方：★ GitHubスターi3つの柱：レビュー · チェック · 利用状況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；只给

冒頭だけを表示しています。続きはリポジトリで読めます

Codex Supervisor MCP

概要

PopNx MCPの3つの柱

できること

インストール

インストールの前に

自分で入力する値

できること

基本チェックi

作者とリポジトリが一致

今もメンテナンスされている

ライセンスがある

エンドポイントが応答する

OAuthでサインイン

ツールの説明に隠れた指示がない

データベース・データセットのほかのサーバーとの比較i

よくある質問

代わりの候補

Supabase

MongoDB MCP Server

Elasticsearch MCP Server

作者のREADME

codex-supervisor-mcp

解决什么

五分钟跑起来

1. 装

2. 派第一批活

3. 开看板

没全局装也能起：

我自己怎么用

看板里有什么

工具