codex-supervisor-mcp

codex-supervisor-mcp

English | 中文

Sitio oficial codex-supervisor.zriyo.com · llms.txt para modelos

Que varios agentes modifiquen el mismo repositorio a la vez termina en sobrescrituras mutuas, nadie sabe quién cambió qué, y el contexto del hilo principal se satura con la salida de los workers.

codex-supervisor-mcp es un servidor MCP de Codex que saca la «asignación de tareas» y el «registro» del contexto del modelo y los pone en disco: un hilo principal (Claude Code, Codex o cualquier cliente MCP) dirige simultáneamente varios workers CLI de Codex, un worker por Git worktree, el estado se guarda en SQLite, con un panel web adjunto.

Prueba real en 30 segundos: create_codex_worker ×3, tres workers en sus propios worktrees en paralelo, el hilo principal recibe 3 diffs y los combina en un solo commit.

Qué resuelve

Problema	Solución
Varios workers se pisan archivos entre sí	Un worker por Git worktree, ownedPaths verifica conflictos antes de asignar
El proceso de los workers satura el contexto del hilo principal	Los eventos se escriben en data/runs/<taskId>.jsonl, con limit / maxChars / kinds como tres filtros al leer
El hilo principal se llena con solo leer el estado una vez	get_orchestration_overview comprime todos los workers en 7000 bytes
Tras reiniciar el proceso no se sabe quién sigue corriendo	supervisor.sqlite un work por línea, con thread_id
Cambiar de sesión no permite retomar los workers anteriores	resume_codex_worker pasa por codex exec resume <thread_id>, conectando a la misma sesión de Codex
No se distingue entre «falló al ejecutar» y «el proceso desapareció»	La máquina de estados separa failed y lost
El worker dice que terminó pero no es cierto	Se asigna con acceptance como comando de verificación; tras salir el worker, el supervisor lo ejecuta en su worktree; si falla, land lo rechaza
No se ve en qué punto está un lote de trabajo	codex-supervisor-web abre un panel para ver qué hace cada worker por sesión

Los workers ejecutan codex exec, con model transparente: el hilo principal se queda en Claude, los workers pueden usar DeepSeek o cualquier modelo con provider configurado en Codex, y las facturas se calculan por separado.

Puesta en marcha en cinco minutos

Requisitos: Node.js 22.13.0 o superior, CLI de codex en PATH. Funciona en macOS, Linux y Windows.

1. Instalación

npm install -g codex-supervisor-mcp

postinstall instala la skill y registra el MCP. Si no aparece en claude mcp list (npx, pnpm, --ignore-scripts no ejecutan postinstall), añádelo manualmente:

claude mcp add -s user codex-supervisor -- npx -y codex-supervisor-mcp
codex mcp add codex-supervisor -- npx -y codex-supervisor-mcp

Reinicia Claude Code / Codex. A partir de ahí no necesitas actualizar manualmente; ver «Actualización». Si solo quieres la skill sin el MCP: npx skills add zriyox/codex-supervisor-mcp.

2. Asigna el primer lote

En Claude Code, di directamente lo que quieres; la skill hará que siga el flujo correcto:

Completa las pruebas unitarias de estos tres módulos, usa codex-supervisor en tres vías paralelas, con la sesión «completar-pruebas».

Lo que hace el hilo principal por detrás (también puedes llamar a las herramientas tú mismo):

create_codex_worker ×3   每路带 session_id、session_title、ownedPaths、goal
wait_codex_workers       默认等 2 分钟，到点返回快照，没完就接着等
get_worker_result ×3     收每路的汇报，带它真跑过的命令和退出码

Los cambios de cada vía están en su propia rama codex/<taskId>; si combinar y cómo hacerlo lo decide el hilo principal.

3. Abre el panel

codex-supervisor-web
# 没全局装也能起：
npx -p codex-supervisor-mcp codex-supervisor-web

Abre http://127.0.0.1:7877. El directorio de estado se busca en este orden: SUPERVISOR_HOME, .mcp.json más reciente, ~/.codex-supervisor; el puerto se cambia con SUPERVISOR_WEB_PORT. El panel es solo de lectura: no asigna ni cancela.

Cómo lo uso yo

Cualquier cosa que pueda conectarse a MCP puede ser el hilo principal; esto es solo mi forma de usarlo. Abro dos sesiones de Claude Code: una solo para documentación y otra solo para asignar tareas: una sesión que escribe el diseño detallado y vigila a los workers llena el contexto en dos horas.

Quién	Dónde se abre	Qué gestiona
Yo		Defino requisitos, tomo decisiones, reviso informes
Sesión de planificación	Repositorio de requisitos y documentación	Converso requisitos, escribo diseño detallado, redacto una especificación por cada bloque de trabajo, con un mensaje final para el cerebro principal
Sesión principal	Un worktree del repositorio de código	Lee la especificación, asigna workers de Codex, revisa los diffs de cada vía, rellena los resultados en la especificación y me informa. No escribe código de negocio
Workers de Codex	Sus propios worktrees	Un worker hace un paso, un commit, compila y verifica en la máquina remota. No hacen push ni merge

Entre las dos sesiones solo se pasa un texto, que se pega en la sesión principal con /goal para conectar. La estructura es fija:

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

Las herramientas que usa la sesión principal en una ronda:

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       核过了，落进集成分支

El bloque anterior tuvo 25 pasos; la sesión principal siguió del paso 1 al 25 en solitario, con solo la especificación y los informes devueltos por cada vía en el contexto, sin saturarse con el proceso de los workers.

Por qué un worker hace solo un paso: si el paso 5 sale mal, el worker que lo hizo hace resume_codex_worker, tras corregir hace --amend y vuelve a su propio commit; la sesión principal revisa de nuevo y solo entonces se integra en la rama de integración. Si un worker hubiera hecho los pasos 5, 6 y 7 seguidos, el error del 5 no se podría corregir así: los commits de 6 y 7 ya están encima del 5, y corregir el 5 obligaría a rehacer también el 6 y el 7.

Qué hay en el panel

Ubicación	Contenido
Columna izquierda	Una línea por sesión: título, número de workers, cuántos en ejecución, actividad reciente. Abajo a la izquierda, versión y aviso de actualización
Página de sesión	Estadísticas (total / en ejecución / completados / fallidos / perdidos); con workers activos, lista el comando que ejecuta cada vía
Registro de workers	Una línea por vía: estado, título, comando en ejecución o último informe, tiempo empleado, archivos modificados, comandos ejecutados
Panel lateral del worker	Siete pestañas: resumen, informes, cambios, comandos, eventos, especificación, consultas
Consultas	Preguntar a ese worker: es el /btw de Codex: bifurca un hilo lateral de solo lectura desde su hilo para responder, sin tocar el trabajo en curso. Multiturno, interrumpible, se retoma solo al volver a la pestaña

El tema claro y oscuro sigue al sistema, sin recursos externos.

Herramientas

Herramienta	Parámetros	Función
create_codex_worker	task, cwd, ownedPaths, goal, acceptance, session_id, session_title, session_note, dependsOn, baseRef, sandbox, model, reasoningEffort, title, skipGitRepoCheck	Inicia un worker. acceptance es el comando de verificación; tras salir el worker, el supervisor lo ejecuta en su worktree; código de salida 0 significa aprobado. baseRef indica desde qué commit se corta el worktree; por defecto HEAD; para conectar con otra vía, usa su codex/<id>
create_codex_followup_worker	task_id, followup_prompt, session_id, el resto igual que arriba	Abre una sesión nueva y combina el prompt, el estado y los eventos recientes del worker anterior
resume_codex_worker	task_id, prompt, rebaseOnto, acceptance	Retoma la misma sesión de Codex; thread_id no cambia. rebaseOnto primero mueve el worktree a la nueva cabeza de la línea principal (stash, reproduce sus commits, lo devuelve); si hay conflicto, lo devuelve tal cual sin iniciar el worker
wait_codex_workers	task_ids, mode(any/all), timeoutMinutes, timeoutMs, compact, includeEvents, eventLimit, eventMaxChars, eventKinds	Espera el estado final. Por defecto 2 minutos; al vencer devuelve con una instantánea y el worker sigue; compact devuelve una línea por vía, con idle_seconds / command_running, para distinguir comandos largos de bloqueos
get_orchestration_overview	status, limit	Tabla de estado de todos los workers, tope de 7000 bytes. Incluye version y update
get_worker_result	task_id, limit, maxChars, includeFiles	Informe del propio worker; por defecto trunca a 6000 bytes, con truncated para leer completo. acceptance indica si la verificación que ejecutó el supervisor pasó; verification son los comandos que ejecutó y sus códigos de salida; base_behind cuánto avanzó la línea principal
get_worker_diff	task_id, maxChars, paths	Qué cambió realmente el worker: el patch desde el inicio del worktree hasta el área de trabajo, incluya commits o no. maxChars controla el total; los archivos que lo superen solo se listan por nombre
ask_codex_worker	task_id, question, timeoutMs, maxChars, fresh, end	Pregunta lateral al worker. El hilo se bifurca en una sesión lateral de solo lectura, sin red ni herramientas MCP; el worker no se mueve. Si el worker fue retomado, se cambia automáticamente a una nueva bifurcación; fresh fuerza el cambio; end elimina
land_codex_worker	task_id, onto, commitMessage, ignoreAcceptance	Hace cherry-pick de los commits del worker en codex/<id> a la rama actual del directorio de asignación. El destino debe estar limpio; si hay conflicto, revierte; la verificación failed rechaza. commitMessage primero commitea los cambios sin confirmar del worker; ignoreAcceptance permite el paso
get_worker_summary	task_id	Un párrafo: objetivo, estado, cambios, último comando y mensaje
get_codex_worker_status	task_id, includePrompt, promptMaxChars	Detalle del estado de un worker individual
get_codex_worker_events	task_id, limit, maxChars, kinds	Flujo de eventos en bruto
get_worker_goal	task_id	El objetivo registrado al asignar + el objetivo nativo de Codex (tokens, tiempo)
list_codex_workers	status, includeHistory, includeDetails	Lista los workers; por defecto solo los activos
get_session_works	session_id	Todos los workers de una sesión. El hilo principal los recupera así tras reiniciar
describe_session	session_id, title, note	Registra título y descripción de la sesión
search_works	query, limit	Busca subcadenas en title / goal / prompt / last_message, de más nuevo a más antiguo
check_for_update	force	Pregunta al registry si hay versión nueva
cancel_codex_worker	task_id	Termina el worker. Respaldo entre procesos por pid; primero confirma que ese pid ejecuta codex

Dos son obligatorios: ownedPaths (intersección entre lo asignado y los workers activos; si se solapan, rechaza; solo se consulta al asignar) y goal.objective (el worker creará el objetivo nativo de Codex). Si session_id no se pasa, no se puede agrupar; un lote usa el mismo valor.

Diferencia con los subagentes de Claude Code

El aislamiento de archivos no es la diferencia: los subagentes también pueden abrir worktrees. La diferencia está en el modelo y el proceso.

	Subagente de Claude Code	Worker de codex-supervisor
Qué modelos puede ejecutar	Solo Claude	model se transmite a la CLI de Codex; DeepSeek también se puede conectar
Quién hace el trabajo	El propio Claude Code	Proceso independiente de codex exec
Dos vías escriben el mismo archivo	Separadas por worktree, sin declaración de rutas	Antes de asignar consulta la intersección de ownedPaths; si se solapan, rechaza directo
El proceso del hilo principal muere	Los workers mueren con él	thread_id está en sqlite; resume_codex_worker retoma la misma sesión
Quién puede dirigirlo	Solo Claude Code	Cualquier cliente MCP
Ver el proceso	Solo la conclusión que devuelve	JSONL en bruto y panel web

Máquina de estados

status	Significado
queued	Asignado, sin iniciar
running	En ejecución. phase: starting → thinking → command → editing → reporting
completed	Éxito
failed	Código de salida distinto de cero, turn.failed, fallo de spawn
cancelled	Interrumpido por cancel_codex_worker
lost	Matado por señal externa, el proceso MCP desapareció, o se escribió la línea pero el proceso nunca arrancó. resume_codex_worker retoma

El estado final se guarda en dos pasos: turn.completed primero pone status en completed; solo tras salir el proceso se escribe exit_code; wait_codex_workers espera a que exit_code esté escrito para devolver. Windows no tiene señales; un kill externo solo reporta failed más el código de salida. El paused / blocked del objetivo nativo de Codex cuenta como running y se suma a needs_attention; usageLimited / budgetLimited cuenta como failed.

Almacenamiento de estado

Por defecto en ~/.codex-supervisor/:

Archivo	Contenido
data/supervisor.sqlite	tasks (un work por línea), task_events, sessions, side_sessions / side_turns (consultas laterales)
data/runs/<taskId>.jsonl	Salida en bruto de --json de Codex
data/update-check.json, auto-update.json	Registros de comprobación de actualizaciones y actualización en segundo plano
worktrees/<taskId>/	El Git worktree de ese worker

changed_files se calcula según el diff real del worktree; lo que el worker cambie con shell o commitee por su cuenta se ve. Los nombres de archivo en chino se devuelven tal cual. Las bases de datos antiguas migran automáticamente al abrir por primera vez.

Variables de entorno

Variable	Por defecto	Función
SUPERVISOR_HOME	~/.codex-supervisor	Directorio raíz de estado. El MCP y el panel deben apuntar al mismo
CODEX_HOME	~/.codex	Solo lectura; lee el goals_1.sqlite nativo de Codex y la configuración MCP
CODEX_BIN	codex	Ruta de la CLI de Codex. En Windows, el shim .cmd se evita automáticamente
GIT_BIN	git	Ruta de Git
SUPERVISOR_WEB_PORT / SUPERVISOR_WEB_HOST	7877 / 127.0.0.1	Dirección de escucha del panel
CODEX_SUPERVISOR_NO_UPDATE_CHECK	Sin definir	1 desactiva la comprobación de actualizaciones
CODEX_SUPERVISOR_REGISTRY	https://registry.npmjs.org	Registry para comprobación y actualización automática
CODEX_SUPERVISOR_UPDATE_TIMEOUT_MS	4000	Límite de espera del registry
CODEX_SUPERVISOR_NO_AUTO_UPDATE	Sin definir	1 desactiva la actualización automática en segundo plano (solo avisa)
CODEX_SUPERVISOR_SKIP_SKILL_SYNC	Sin definir	1 desactiva la sincronización de skills al iniciar el servidor
CODEX_SUPERVISOR_SKIP_SETUP	Sin definir	1 omite la instalación automática de postinstall
CODEX_SUPERVISOR_NPM	Sin definir	npm para la actualización automática; por defecto usa el que trae el Node actual

Los clientes GUI (Claude Desktop, Cursor, Windsurf) no ejecutan postinstall; añade este bloque a su archivo de configuración MCP. En PATH a menudo no hay codex; pásalo explícitamente con CODEX_BIN:

{
  "mcpServers": {
    "codex-supervisor": {
      "command": "npx",
      "args": ["-y", "codex-supervisor-mcp"],
      "env": { "CODEX_BIN": "/usr/local/bin/codex" }
    }
  }
}

Actualización

No hace falta actualizar a mano. Al iniciar, el servidor consulta el registry en segundo plano; si hay versión nueva, lanza un proceso independiente npm i -g a la misma ruta global; las sesiones en curso no se ven afectadas; la próxima sesión nueva ya será la versión nueva. Solo afecta a la copia instalada por npm i -g; no toca el código fuente de git ni lo iniciado con npx. La skill igual: en cada arranque se actualiza al directorio de skills existente; lo modificado se respalda primero como SKILL.md.bak-<时间戳>.

Si la instalación falla (el directorio global requiere sudo), el campo update lleva el motivo; haz npm install -g codex-supervisor-mcp@latest manualmente. En 0.6.1 y anteriores solo avisa sin instalar automáticamente; una actualización manual entra en el modo automático. Si cambias de versión de Node, la ruta registrada deja de funcionar; tras claude mcp remove -s user codex-supervisor, codex mcp remove codex-supervisor, reinstala. Para reinstalar: codex-supervisor-setup (--skill-only / --mcp-only / --dry-run).

Desinstalación:

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

• La CLI instalada por npm es codex.cmd; Node se niega a hacer spawn directo. Aquí se evita con node_modules/@openai/codex/bin/codex.js usando node, sin shell: true: así, al cancelar solo se mataría el shell.
• La cancelación entre procesos usa taskkill /PID <pid> /T /F para matar todo el árbol; primero confirma que ese pid ejecuta codex.
• Además de PATH, también detecta %APPDATA%\npm, %LOCALAPPDATA%\pnpm, %LOCALAPPDATA%\Volta\bin, %ProgramFiles%\nodejs.

Solución de problemas

Síntoma	Causa	Solución
No aparece en claude mcp list	El método de instalación no ejecuta postinstall	codex-supervisor-setup o claude mcp add manual
Al asignar da codex only resolved to a shell shim	Windows solo encuentra .cmd y la entrada del paquete desapareció	Reinstala @openai/codex, o CODEX_BIN apunta a codex.js
El worker sale con failed nada más arrancar, spawn codex ENOENT	El proceso PATH no tiene codex	Configura CODEX_BIN
Cannot find module 'node:sqlite'	Node inferior a 22.13.0	Actualiza Node
El worker lost	El proceso MCP fue matado y el worker cayó con él	resume_codex_worker retoma
El worker dice git add y reporta index.lock: Operation not permitted	El sandbox por defecto pone .git en solo lectura	Al recoger, land_codex_worker con commitMessage, o asigna con danger-full-access
ownedPaths overlap with active worker(s)	Dos vías reclamaron la misma zona de rutas	Cambia la división, o cancela primero la vía que la ocupa
El panel se abre vacío	El SUPERVISOR_HOME del panel y del MCP no es el mismo	Inicia en el directorio del proyecto con .mcp.json, o pasa explícitamente el mismo SUPERVISOR_HOME
port 7877 ... is already in use	Ya hay un panel en ejecución	Ábrelo directamente, o SUPERVISOR_WEB_PORT=8080 y levanta otro

Limitaciones conocidas

• El worker es un subproceso del proceso MCP. Si el MCP recibe kill, el worker cae con él y se liquida como lost; el worktree y thread_id siguen ahí; resume_codex_worker retoma. Para que no muera con él haría falta un daemon residente, en el Roadmap.
• En el sandbox por defecto de workspace-write, el worker no puede commitear (Codex pone .git en solo lectura). O al recoger, land_codex_worker con commitMessage commitea por él, o asigna con danger-full-access.
• El worktree se corta desde un commit; lo que no esté commiteado en tu área de trabajo no está dentro.
• Solo aísla el directorio de trabajo. Los directorios temporales, la base de datos y los puertos son compartidos.
• ownedPaths solo se consulta al asignar; no impide que el worker cree archivos fuera de la lista. Al recoger, revisa el diff.
• La verificación comprueba solo lo que esté escrito en acceptance. Lo que no esté ahí no lo comprueba por ti; verification son solo los comandos que el worker ejecutó; el resto depende de que el hilo principal revise el diff.
• Una sola llamada a wait_codex_workers no llega hasta el final; el tiempo de espera de las herramientas MCP del cliente es un muro duro; se resuelve llamando repetidamente.
• search_works es coincidencia de subcadenas; con unos cientos de entradas es suficiente.

Roadmap

Hecho: CODEX_BIN / SUPERVISOR_HOME / GIT_BIN; status y phase separados; ownedPaths / goal / dependsOn; thread_id en base de datos + resume_codex_worker; concurrencia y escritura multiproceso en la base; session_id, search_works, objetivo nativo; Windows; panel web; baseRef; trío de recogida get_worker_diff / ask_codex_worker / land_codex_worker; actualización automática en segundo plano.

Siguiente: daemon residente, sacar la asignación y el ciclo de vida de los procesos del proceso MCP.

No se hará: búsqueda vectorial (la coincidencia de subcadenas es más rápida y sin mantenimiento a esta escala), ordenación por usage_count (en la práctica, de 80 works solo 2 fueron referenciados de nuevo).

Desarrollo

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 ejecuta Ubuntu / macOS / Windows, más un job con Node 22.13.0 para fijar el límite inferior de engines.

Contribuciones

Consulta CONTRIBUTING.md. Los problemas de seguridad se gestionan por canal privado, consulta SECURITY.md.

Licencia

MIT