hierarchical-codex

hierarchical-codex es un plano de control MCP determinista para los subagentes nativos de Codex. Codex sigue creando hilos Sol → Terra → Luna visibles en la interfaz con spawn_agent; este proyecto aporta el estado persistente, los puntos de control de políticas, los presupuestos, los artefactos, el flujo de trabajo de evidencia y el protocolo de recuperación en torno a esos hilos.

Estado: MVP de ingeniería. El plano de control, la integración con el proyecto Codex, los hooks, las pruebas y la documentación operativa están implementados. Valida la disponibilidad del modelo y la versión exacta del núcleo de Codex en cada despliegue de App/IDE objetivo.

Decisión de diseño

El proyecto sigue una ruta explícita:

Generación de subagentes dirigida por el modelo; restricciones impuestas por el código.

Codex native execution plane
  spawn_agent / wait_agent / send_message / Subagents UI
                  |
                  | task_id in TaskEnvelope
                  v
TypeScript MCP control plane
  SQLite task ledger / leases / budgets / artifacts / evidence / audit
                  ^
                  |
Codex Skills + Profiles + Hooks
  orchestration policy / model-effort routing / spawn veto / stop checks

MCP y hooks no crean hilos nativos. El modelo Sol o Terra llama al spawn_agent nativo; el código valida y registra el flujo de trabajo que lo rodea.

Related MCP server: dingdawg-governance

Funcionalidades implementadas

• Registros de misiones y tareas con versionado optimista.

• Política de rol de padre directo: Sol director → Terra coordinador → Luna hoja.

• Matriz modelo/esfuerzo:

  • Sol: high, xhigh, max

  • Terra: xhigh, max

  • Luna: high, xhigh, max

• Preparación consciente de las dependencias y asignación limitada de hijos.

• Arrendamientos de trabajo caducables, latidos de corazón, liberación y reclamación segura.

• Presupuestos jerárquicos de tokens, coste, tiempo de muro, llamadas a herramientas y recuento de hijos.

• Almacenamiento de artefactos direccionado por contenido con lecturas limitadas.

• Compuertas de evidencia: candidato → comprobado → verificado → confirmado.

• Separación entre productor y revisor.

• Mutaciones idempotentes con hash de solicitud y eventos de auditoría de solo adición.

• Instantáneas de recuperación tras un reinicio o una compactación de contexto.

• Skill de Codex con ámbito de proyecto, perfiles de agentes, configuración de MCP y hooks.

Requisitos

• Node.js 22.5 o más reciente. En desarrollo se usa Node 26.

• Python 3.10 o más reciente para los hooks del ciclo de vida de Codex.

• Codex 0.148.0 o más reciente es la base de referencia recomendada para producción, con herramientas multiagente nativas, agentes personalizados, MCP y hooks.

• Un proyecto de Codex en el que se confíe para que se carguen .codex/config.toml y los hooks del proyecto.

Inicio rápido

cd "/mnt/tools/others/codes/web project/hierarchical-codex"
npm install
npm run check
npm run doctor

A continuación:

1. Abre la raíz de este repositorio en Codex App, Codex CLI o la extensión Codex para VS Code. npm run doctor no instala la skill en ChatGPT; la App debe usar esta carpeta como espacio de trabajo.

2. Confía en el proyecto cuando se te pida. Los proyectos en los que no se confía ocultan las skills de .codex.

3. Inicia una conversación raíz nueva con gpt-5.6-sol (las skills se cargan al inicio).

4. Escribe $ y selecciona prism, o invoca $prism <mission>. Si el selector está vacío, AGENTS.md sigue dirigiendo al Sol raíz.

5. Inspecciona la actividad nativa de los subagentes en la interfaz Subagents y el estado persistente a través de las herramientas de MCP.

Para usar la pila completa desde otras carpetas en la extensión Codex de VS Code o la CLI, ejecuta npm run install:user después de npm run build. Ver docs de USUARIO. No copies el .codex/config.toml de este repositorio en ~/.codex; fijaría a Sol como el modelo predeterminado y bloquearía los subagentes normales.

La configuración MCP del proyecto lanza node dist/cli.js con la raíz del repositorio como directorio de trabajo. Ejecuta npm run build tras los cambios en el código fuente.

Comandos de desarrollo

npm run dev          # Run the stdio MCP server from TypeScript
npm run doctor       # Validate runtime and Codex integration files
npm run test         # Unit and integration tests
npm run typecheck    # Strict TypeScript checks
npm run lint         # ESLint
npm run format       # Prettier
npm run build        # Compile dist/
npm run check          # Full local quality gate
npm run install:user   # Install skill, agents, hooks, and MCP into ~/.codex
npm run doctor:user    # Verify the user-global install
npm run uninstall:user # Remove the managed user-global files

El servidor MCP escribe los mensajes de protocolo en stdout. El registro de la aplicación debe usar stderr; el registro en stdout corrompe el transporte MCP stdio.

Estado del flujo

Por defecto, el estado es local al proyecto y Git lo ignora:

.hierarchical-codex/
├── control-plane.sqlite
└── artifacts/
    └── <sha-prefix>/<sha256>

La instalación de usuario global (npm run install:user) guarda el registro en ~/.local/share/hierarchical-codex/ para que los entorno de MCP de Codex puedan escribir en él. Si ese directorio no es escribible, el servidor recurre a una ruta temporal y anuncia en el stderr el home elegido.

Variables de entorno de configuración:

• HIERARCHICAL_CODEX_HOME

• HIERARCHICAL_CODEX_DB

• HIERARCHICAL_CODEX_ARTIFACTS

• HIERARCHICAL_CODEX_MAX_ARTIFACT_BYTES

• HIERARCHICAL_CODEX_DEFAULT_LEASE_SECONDS

• HIERARCHICAL_CODEX_MAX_LEASE_SECONDS

• HIERARCHICAL_CODEX_EVENT_PAGE_SIZE

Herramientas MCP

Misión:

• mission_create

• mission_get

• mission_close

Tarea y arrendamiento:

• task_allocate

• task_get

• task_claim

• task_start

• task_heartbeat

• task_release

• task_block

• task_fail

• task_cancel

• task_supersede

• task_set_effort

• task_commit

Artefactos y evidencia:

• artifact_put

• artifact_get

• result_submit_candidate

• result_check

• result_verify

Contabilidad y recuperación:

• budget_report

• recovery_snapshot

Consulta docs/API.md para los contratos y docs/PROTOCOL.md para la secuencia de orquestación.

Estructura del repositorio

.agents/skills/             Codex orchestration Skill
.codex/agents/              Sol/Terra/Luna custom profiles
.codex/hooks/               Python policy gates
.codex/config.toml          MCP and native agent configuration
src/domain/                 State and policy definitions
src/infra/                  SQLite repository and artifact storage
src/mcp/                    MCP tool registration
tests/                      Control-plane, policy, and hook tests
docs/                       Architecture, protocol, operations, ADRs, records

Límites importantes

• El código MCP externo no puede llamar al registro nativo spawn_agent.

• Los hooks pueden denegar, reescribir o añadir contexto, pero SubagentStart no puede impedir que haya un subagente después de su creación.

• El estado nativo de la interfaz es observacional; SQLite es la fuente persistente del trabajo.

• Este MVP es de un único host. SQLite serializa las mutaciones, pero no es un sistema de consenso distribuible.

• El uso de tokens lo informan los agentes; el servidor MCP no puede medir de forma independiente los tokens del modelo.

• El repositorio está actualmente UNLICENSED; añade una licencia explícita antes de cualquier distribución externa.

Documentación

• Arquitectura

• Protocolo

• API de MCP

• Integración con Codex

• Instalación global de usuario en VS Code / CLI

• Operaciones

• Modelo de seguridad

• Guía de desarrollo

• Estrategia de pruebas

• Hoja de ruta

• Registro de cambios

• Registro de la implementación

• Decisiones de arquitectura