Codex Supervisor MCP

Name: Codex Supervisor MCP
Author: zriyox

by zriyoxversion 0.8.0i★ –iRuns on your computer

Registry nameio.github.zriyox/codex-supervisor-mcp

Install

Overview

Description from the maker (original English)

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

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiNot measured yet★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Databases & datasets

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
You fill in yourself: CODEX_BIN, SUPERVISOR_HOME

You need

npmNode.js installed (for the npx command)

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

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

Run this in your terminal

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

Fill in the empty values before running it.

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

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

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

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

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

Values you fill in

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

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 7, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account zriyox, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Databases & datasetsi

More stars than 0% of the other 952 servers in this category
Published to the registry more recently than 66% of the other 952 servers in this category
Basic checks equal to or better than 100% of the other 952 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is Codex Supervisor MCP safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.8.0) reached the registry 29 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Node.js on your computer.

What can I use instead?

In the same category: Supabase, MongoDB MCP Server, Elasticsearch MCP Server

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

Supabase

by supabase

Supabase’s official server lets AI create tables, query data and review project settings in your Supabase database.

Computer or cloud★ 2,993Apache-2.0Updated today

Install

MongoDB MCP Server

by mongodb-js

MongoDB Model Context Protocol Server

Runs on your computer★ 1,157Apache-2.0Updated 2 days ago

Install

Elasticsearch MCP Server

by cr7258

MCP server for interacting with Elasticsearch

Runs on your computer★ 315Apache-2.0Updated 14 months ago

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

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；只给

Only the beginning is shown; read the rest in the repo

Codex Supervisor MCP

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

Values you fill in

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Databases & datasetsi

Common questions

Alternatives

Supabase

MongoDB MCP Server

Elasticsearch MCP Server

README from the maker

codex-supervisor-mcp

解决什么

五分钟跑起来

1. 装

2. 派第一批活

3. 开看板

没全局装也能起：

我自己怎么用

看板里有什么

工具