BoundedRelay

BoundedRelay permite que Claude Code entregue una tarea bien delimitada a la CLI de Codex instalada localmente a través de MCP. La llamada devuelve de inmediato un identificador de trabajo. Claude puede entonces mostrar lo que el worker está haciendo, esperar de forma eficiente la siguiente actualización real, recuperar el resultado o cancelar el trabajo.

Claude Code  ── local MCP/stdio ──>  BoundedRelay  ── codex exec --json ──>  Codex
                                             │
                                             ├─ policy and resource limits
                                             ├─ sanitized live activity
                                             └─ isolated proposal clone

La topología v0.1 admitida es deliberadamente unidireccional: Claude Code → BoundedRelay → Codex. BoundedRelay no proporciona una ruta de retorno de Codex a Claude, y el worker nunca aplica los cambios generados al repositorio fuente.

[!IMPORTANT] BoundedRelay es un proyecto comunitario independiente. No está afiliado, respaldado ni mantenido por Anthropic ni por OpenAI. Claude, Claude Code, Codex y OpenAI son marcas comerciales de sus respectivos propietarios.

La versión 0.1.0 es una versión de desarrollo local. El paquete npm aún no está publicado, y v0.1 no tiene servicio remoto, daemon, base de datos, almacén de trabajos persistente ni registro de auditoría.

Por qué BoundedRelay

• Visible en lugar de congelado: etiquetas de actividad seguras, contadores de eventos, tiempo transcurrido, tiempo desde la última actualización, posición en la cola y sondeo consciente de revisiones.

• Solo lectura por defecto: el análisis siempre solicita el sandbox read-only de Codex.

• Autoridad acotada: el servidor es propietario de las raíces de los espacios de trabajo, las anulaciones de modelo, el reenvío de variables de entorno, los tiempos de espera, la concurrencia, la salida y los límites de parches.

• Revisión antes de la mutación: el modo de propuesta trabaja en un clon desechable, valida el parche resultante y nunca lo aplica.

• Sin progreso falso: BoundedRelay informa de la actividad observada del ciclo de vida. No inventa un porcentaje completado ni una ETA.

• Superficie pública pequeña: herramientas MCP específicas para descubrimiento de capacidades, inspección del espacio de trabajo, envío, estado, resultado, cancelación e historial.

Lo que Claude puede mostrar mientras Codex trabaja

codex_worker_status devuelve una instantánea saneada como esta:

{
  "status": "running",
  "revision": 14,
  "progress": {
    "phase": "working",
    "activity": "running_command",
    "activityLabel": "Codex is running a sandboxed command",
    "eventCount": 8,
    "commandCount": 2,
    "messageCount": 0,
    "lastEventType": "item.started",
    "updatedAt": "2026-08-27T18:30:00.000Z",
    "elapsedMs": 12420,
    "sinceLastUpdateMs": 180
  }
}

La superficie de estado expone un vocabulario de actividad fijo y propiedad del servidor. No expone cadenas de pensamiento, texto de comandos, argumentos de herramientas, rutas de archivos del repositorio procedentes de eventos ni cargas útiles arbitrarias de eventos de Codex.

Related MCP server: cc-in-codex

Dónde encaja esto

Para la delegación general de Claude Code a Codex, evalúa primero el openai/codex-plugin-cc oficial de OpenAI. Usa BoundedRelay cuando necesites específicamente un límite de política MCP local alrededor del subproceso de Codex.

Consulta la comparación detallada.

Requisitos previos

• Node.js >=22.13.0 y npm;

• Git disponible en PATH;

• CLI de Codex instalada y autenticada para el usuario actual del sistema operativo;

• Claude Code con soporte MCP stdio local;

• un repositorio Git para cada tarea delegada.

BoundedRelay utiliza la interfaz no interactiva admitida codex exec --json. No tiene entrada de credenciales ni almacén de credenciales. La autenticación guardada de Codex se utiliza a través del entorno normal del usuario; el reenvío directo de tokens de API es una opción adicional independiente.

Inicio rápido desde el código fuente

El paquete aún no está en npm. Clona o descarga este repositorio y ejecútalo localmente.

1. Instala, verifica e inspecciona el entorno local

git clone <repository-url> bounded-relay
cd bounded-relay
npm ci
npm run check
node dist/cli.js doctor

doctor comprueba las dependencias relacionadas con Node, la compatibilidad del comando de Codex, Git y el estado de inicio de sesión de Codex sin realizar una llamada de modelo.

2. Registra el worker compilado con Claude Code

Ejecuta esto desde el directorio de BoundedRelay para que el shell registre una ruta absoluta. El ámbito de usuario es el valor predeterminado personal recomendado porque la misma instalación está disponible cuando Claude Code abre otros proyectos:

WORKER_ENTRY="$(pwd)/dist/cli.js"

claude mcp add \
  --transport stdio \
  --scope user \
  bounded-relay \
  -- node "$WORKER_ENTRY" serve

--scope user es personal para tu cuenta del sistema operativo y no se confirma en un repositorio. Para mantener el registro local en un solo proyecto, cambia al repositorio Git de destino antes de ejecutar el comando y usa --scope local; el ámbito local pertenece al proyecto en el que se ejecuta el comando.

Luego verifica:

claude mcp list

Dentro de Claude Code, ejecuta /mcp. bounded-relay debería aparecer como conectado.

3. Ejecuta la primera delegación de solo lectura

Abre Claude Code dentro de un repositorio Git y pide:

Use bounded-relay to inspect this workspace and start a read-only architecture review.
Poll codex_worker_status with afterRevision so you show each new activity without spam.
When the job completes, retrieve the result and summarize only high-confidence findings.

Claude debería usar codex_worker_workspace, codex_worker_analyze, codex_worker_status y codex_worker_result.

Para macOS, Linux, Windows PowerShell, configuración con ámbito de proyecto, eliminación, actualizaciones y fallos de configuración comunes, lee la guía completa de instalación y primer uso.

Herramientas MCP

Los espacios de nombres estables de protocolo/configuración v0.1 siguen siendo codex_worker_* y CCW_*. La marca pública es BoundedRelay; mantener esos espacios de nombres explícitos evita una migración disruptiva innecesaria antes de que el contrato se estabilice.

Lee la referencia completa de herramientas, incluidos todos los estados de actividad, entradas, salidas y códigos de fallo.

Contrato de seguridad

Modo de análisis — predeterminado

• Solicita el sandbox read-only de Codex en un repositorio Git permitido canónico.

• Rechaza campos exclusivos de propuesta como writePaths y expectedRevision.

• Devuelve el análisis final de Codex junto con los metadatos de uso observados.

Modo de propuesta — deshabilitado por defecto

• Se registra solo cuando el servidor se inicia con CCW_ENABLE_PROPOSALS=true.

• Requiere un árbol de origen limpio, un ID de objeto Git completo exacto y rutas de escritura explícitas relativas al repositorio.

• Crea un clon desechable limpio en la revisión fijada.

• Ejecuta workspace-write solo dentro de ese clon.

• Rechaza refs modificadas, HEAD modificado, archivos fuera de alcance, rutas protegidas, cambios de enlaces simbólicos, parches sobredimensionados y recuentos excesivos de archivos modificados.

• Devuelve un parche binario de índice completo validado y un resumen SHA-256, y luego elimina el clon.

• Nunca aplica, confirma, envía, publica ni despliega el parche.

Actívalo solo después de que el modo de solo lectura funcione:

claude mcp remove bounded-relay --scope user

claude mcp add \
  --env CCW_ENABLE_PROPOSALS=true \
  --transport stdio \
  --scope user \
  bounded-relay \
  -- node /absolute/path/to/bounded-relay/dist/cli.js serve

codex_worker_result omite el texto del parche por defecto. Un llamador debe solicitar includePatch=true, verificar el resumen devuelto, revisar el contenido y decidir por separado si lo aplica. Lee el modelo de seguridad completo antes de activar las propuestas.

Arquitectura

flowchart LR
    Claude[Claude Code] -->|local MCP over stdio| Relay[BoundedRelay]
    Relay --> Policy[Validation and policy]
    Policy --> Queue[Bounded in-memory queue]
    Queue --> Analyze[Read-only analysis]
    Queue --> Proposal[Isolated proposal]
    Analyze -->|codex exec --json| Codex[Codex CLI]
    Proposal --> Clone[Disposable clean clone]
    Clone -->|workspace-write only here| Codex
    Codex --> Events[Sanitized activity]
    Clone --> Patch[Validated patch artifact]
    Events --> Relay
    Patch --> Relay

Consulta Arquitectura y los registros de decisiones de arquitectura.

Flujo de trabajo opcional con Spec Kit

Spec Kit es útil para funciones sustanciales de proyectos de consumo porque crea artefactos de especificación, plan y tareas revisables antes de la implementación. Intencionalmente no es una dependencia de ejecución de BoundedRelay y este repositorio no incluye un espacio de trabajo .specify/.

La integración recomendada añade tres puertas de revisión:

1. Claude redacta el plan de Spec Kit; Codex realiza una revisión acotada de solo lectura del plan antes de que se finalicen las tareas.

2. Después de que se generen las tareas y el análisis de Spec Kit pase, Codex verifica spec.md, plan.md y tasks.md como un único contrato entre artefactos.

3. Después de la implementación y las comprobaciones del proyecto, Claude revisa el diff y Codex lo verifica de forma independiente contra los artefactos aprobados.

Una puerta estricta revisa los artefactos confirmados en un espacio de trabajo limpio, registra el HEAD de Git exacto y la revisión del artefacto, y queda obsoleta después de cualquier cambio en un artefacto revisado o en HEAD. Una revisión de borrador puede inspeccionar trabajo sin confirmar, pero sus hallazgos sin versionar son orientativos y no pueden satisfacer una puerta estricta.

Usa la guía de integración de Spec Kit fijada y opcional.

Configuración

Los valores predeterminados seguros no requieren configuración de proyecto.

Lee Configuración antes de reenviar secretos o activar propuestas.

Lo que BoundedRelay no afirma

• No selecciona un modelo objetivamente “mejor”. Los valores opcionales de modelo y razonamiento siguen siendo opciones explícitas incluidas en la lista blanca del servidor.

• No garantiza un mejor código, un menor uso de tokens ni un menor coste.

• No expone la cadena de pensamiento privada como progreso.

• No mantiene trabajos activos después de que el proceso del servidor stdio finalice.

• No impide escrituras realizadas manualmente o por herramientas no relacionadas.

• No hace que Codex funcione sin conexión ni cambia las políticas de retención del proveedor.

• No aplica automáticamente, ni hace commit, ni hace push, ni publica, ni despliega ni muta el estado remoto.

Documentación

• Primeros pasos

• Índice de documentación

• Arquitectura

• Modelo de seguridad

• Estado en directo y herramientas MCP

• Configuración

• Compatibilidad

• Integración con Spec Kit

• Solución de problemas

• Desarrollo

• Hoja de ruta

• Recetas

• Recursos de marca y notas de generación

Estado del proyecto

0.1.0 es intencionadamente una versión previa a la estable. Los contratos pueden cambiar antes de 1.0.0. Consulta CHANGELOG.md y las notas de compatibilidad antes de actualizar.

Contribución, seguridad y soporte

• Lee CONTRIBUTING.md antes de abrir una pull request.

• Notifica vulnerabilidades de forma privada a través de SECURITY.md.

• Usa SUPPORT.md para conocer los límites del soporte y los detalles de diagnóstico.

Licencia

MIT