AgentBridge

Estado: migración en curso, y este README describe la forma anterior.

AgentBridge comenzó como un puente de Claude-Code a Codex/Antigravity, y todo lo documentado a continuación funciona hoy. Se está generalizando para que cualquier CLI compatible pueda ser el orquestador y cualquier otro pueda ser un trabajador, con enrutamiento impulsado por un perfil por usuario en lugar de nombres de modelo codificados.

Para saber hacia dónde va, lea docs/architecture.md y docs/roles.md. En curso: una capa de adaptadores de proveedor (src/providers/), un perfil de enrutamiento (src/profile/), y un flujo de configuración agentbridge init. El adaptador de Cursor está presente pero sin verificar — sus banderas se escribieron a partir de conocimiento previo en lugar de leerse de un CLI instalado, y así se indica en la parte superior del archivo.

Hasta que la migración se complete, trate las secciones a continuación como precisas para los trabajadores de Codex y Antigravity, y los documentos como precisos para el diseño.

Orquestadores

AgentBridge sirve su superficie de comandos /agentbridge … como prompts de MCP, por lo que cualquier cliente MCP que admita prompts/list recibe los mismos comandos del propio servidor — sin archivos de comandos por host que instalar o mantener sincronizados.

La doctrina detrás de esos comandos vive en doctrine/ y no menciona modelos — enruta por rol, y .agentbridge/profile.json asigna roles a lo que el usuario realmente tiene instalado.

Un pequeño servidor MCP stdio local que permite a Claude Code delegar trabajo al Codex CLI y al Antigravity CLI (agy) como trabajadores externos — usando las sesiones de CLI en las que ya has iniciado sesión, sin claves de API.

Claude sigue siendo el orquestador. AgentBridge es deliberadamente una tubería tonta: convierte la solicitud estructurada de Claude en un prompt de trabajador, ejecuta el CLI y devuelve un resultado estructurado compacto.

User
 └─> Claude Code                      (orchestrator — decides what to delegate)
      └─> AgentBridge MCP tool        (codex_run / antigravity_run)
           └─> codex exec  |  agy --print
                └─> result
           <─ structured MCP result
      <─ Claude inspects the work and continues

Related MCP server: agent-intern

Lo que no es

Sin servicio en la nube, interfaz web, base de datos, demonio, panel de control, cola de trabajos, sistema de cuentas o gestión de claves de API. Es un proceso Node que Claude Code inicia a través de stdio y detiene cuando sale.

Cómo funciona

1. Claude llama a codex_run o antigravity_run con una solicitud estructurada (objetivo, modo, modelo, esfuerzo, rutas, contrato, criterios de aceptación…).

2. AgentBridge ensambla un prompt de trabajador exactamente a partir de esos campos. No ejecuta ningún modelo propio — esto es ensamblaje de cadenas, no inferencia.

3. Reserva ámbitos de escritura, toma una instantánea del árbol de trabajo de git y lanza el CLI con una matriz de argumentos (shell: false).

4. Analiza la salida legible por máquina del CLI, extrae el resultado final del trabajador (nunca su razonamiento interno), compara el árbol de git para determinar qué cambió realmente, y devuelve un resultado JSON compacto.

Una llamada MCP = un intento de trabajador. AgentBridge nunca reintenta. Si vale la pena otro intento es decisión de Claude.

Requisitos

AgentBridge nunca lee, copia, exporta ni modifica tus credenciales de Codex o Antigravity. Invoca los CLIs exactamente como lo haría un humano con sesión iniciada.

Instalación y compilación

npm install

npm run build

npm test

El conjunto de pruebas utiliza procesos simulados en todo momento, por lo que un npm test normal consume sin cuota de modelo.

Registro con Claude Code

Regístrese una vez en el ámbito de usuario para que cada proyecto pueda usarlo:

claude mcp add --transport stdio --scope user agentbridge -- node D:\Code\Agentbridge\dist\index.js

Verifique desde una terminal:

claude mcp list

claude mcp get agentbridge

Luego verifique dentro de Claude Code ejecutando /mcp. Debería ver agentbridge listado como conectado, con tres herramientas: codex_run, antigravity_run, bridge_status. Pida a Claude que llame a bridge_status para un informe de salud completo.

Si reconstruye AgentBridge, reinicie Claude Code (o reconecte el servidor desde /mcp) para que tome el nuevo dist/.

Directorio del proyecto

Los trabajadores se ejecutan en, y están limitados a, un único directorio de proyecto, resuelto en este orden:

1. AGENTBRIDGE_PROJECT_DIR, luego la variable heredada CLAUDE_PROJECT_DIR (que Claude Code exporta).

2. La primera raíz file:// que el cliente MCP anuncie.

3. El directorio de trabajo del proceso del servidor.

bridge_status informa cuál se usó.

Herramientas

codex_run

Modelos. Tres slugs son direccionables, y cada uno se pasa al CLI tal cual:

Mapeo de esfuerzo (etiqueta del orquestador → model_reasoning_effort de Codex):

El mapeo es total y determinista. El nivel ultra de Codex se expone deliberadamente no: solo algunos modelos lo ofrecen, y una sexta etiqueta que funcione para dos de tres modelos haría que el enrutamiento dependiera del modelo.

Disponibilidad. Antes de lanzar, AgentBridge verifica el modelo y el esfuerzo solicitados contra el catálogo de modelos del propio Codex CLI (models_cache.json en CODEX_HOME) — una lectura de archivo, sin inferencia.

• modelo listado, esfuerzo listado → el trabajo se ejecuta

• modelo listado, esfuerzo no → invalid_effort, con details.supported_efforts

• modelo no listado → requested_model_unavailable, con details.available_models

• sin catálogo legible → el trabajo se ejecuta de todos modos, con una advertencia de que la disponibilidad era unverified

Nunca se sustituye nada por otra cosa. Una decisión de enrutamiento que no se puede honrar regresa como un error estructurado que lleva suficiente metadatos para reenrutar en un solo paso, en lugar de como un modelo silenciosamente más débil.

La invocación construida es:

codex exec --json --skip-git-repo-check -m <MODEL> -c model_reasoning_effort="<EFFORT>" \
           -s <read-only|workspace-write> -C <PROJECT> -o <tmpfile> --color never

con el prompt transmitido por stdin. El modelo, el esfuerzo y el sandbox se pasan en cada llamada, por lo que una ejecución nunca hereda lo que esté configurado en ~/.codex/config.toml.

analyze y review usan el sandbox read-only real de Codex — las escrituras están genuinamente prevenidas, no solo desaconsejadas.

antigravity_run

Mismo esquema, con:

Los nombres lógicos se resuelven en tiempo de ejecución contra la lista agy models en vivo:

Antigravity codifica el nivel de razonamiento en el id del modelo, por lo que model + effort se resuelven a un solo id y no se envía ninguna bandera --effort separada — los dos nunca pueden discrepar. Flash tiene solo estos tres niveles: extra high y max devuelven invalid_effort en lugar de ejecutar silenciosamente un nivel más débil del que pediste.

Antigravity está intencionalmente limitado al nivel Gemini económico. Los modelos Claude que agy también ofrece no se exponen como etiquetas enrutables — para razonamiento de clase Claude, use Claude Code o Codex, que tienen sandboxing real y (para Codex) esfuerzo seleccionable.

La etiqueta tiene una lista ordenada de candidatos de ids para el mismo modelo. Si ninguno de ellos es ofrecido por la CLI instalada, la llamada falla con requested_model_unavailable y la lista completa de modelos disponibles. Nunca cae silenciosamente a un modelo diferente. El id resuelto se devuelve en warnings en cada ejecución.

La invocación construida es:

agy --print <PROMPT> --model <RESOLVED_ID> --output-format json \
    --mode <plan|accept-edits> --add-dir <PROJECT> \
    --dangerously-skip-permissions --print-timeout <N>s

--disable-slash-commands se añade solo para ejecuciones de implement: la CLI ignora --mode plan siempre que la expansión de slash-commands esté deshabilitada, así que enviar ambos descartaría silenciosamente el único comportamiento sin escritura que Antigravity ofrece.

bridge_status

Sin argumentos. Consume ninguna inferencia de modelo — solo ejecuta sondeos de --version, agy models, un git rev-parse, y una lectura de la caché de modelos de la CLI de Codex.

Devuelve:

• Versión de AgentBridge, directorio del proyecto (y cómo se resolvió), node/plataforma

• git_verification — si files_changed / scope_violations basados en git funcionarán aquí en absoluto. Cuando no sea así, un scope_violations vacío es silencio, no un certificado de salud, y los warnings lo indican

• codex.installed / version / path / auth

• codex.model_status — por modelo: available | unavailable | unverified, las etiquetas de esfuerzo que AgentBridge acepta, y los niveles de razonamiento crudos de la CLI

• codex.model_source — de dónde proviene la disponibilidad y qué fresca es

• antigravity.installed / version / path / auth, modelos detectados, cómo cada etiqueta lógica + nivel se resolvió, y model_status con la misma forma de tres estados

• antigravity.unsupported_efforts — las etiquetas del orquestador que Flash no puede tomar

• trabajos activos y sus ámbitos de escritura

• warnings

La disponibilidad nunca se adivina. Cuando la CLI instalada no ofrece una prueba barata, el estado es unverified en lugar de una afirmación en cualquier dirección.

Nunca devuelve credenciales ni variables de entorno.

Formato de resultado

{
  "status": "success",
  "provider": "codex",
  "model": "gpt-5.6-luna",
  "effort": "high",
  "mode": "implement",
  "duration_ms": 12345,
  "exit_code": 0,
  "summary": "...",
  "files_changed": ["src/upload.ts"],
  "scope_violations": [],
  "tests_or_checks_run": ["npm test -- upload"],
  "test_results": "12 passed",
  "concerns_or_blockers": [],
  "stderr_tail": "",
  "warnings": []
}

effort está presente para ambos proveedores — el nivel de razonamiento de Codex, o el nivel de Flash que el id del modelo codifica. files_changed y scope_violations son calculados por AgentBridge desde git, no tomados de la palabra del trabajador. El razonamiento interno se descarta. summary está limitado a 16 000 caracteres, conservando la cabeza y la cola y estableciendo summary_truncated: true cuando recorta.

Errores

Los fallos devuelven la misma forma de envoltorio con status: "failed", una categoría de error, un message accionable, y — cuando esté disponible — exit_code, stderr_tail, y un objeto details.

Ejemplos de Claude llamando a los trabajadores

Análisis barato y rápido:

{ "tool": "codex_run",
  "goal": "Explain how session refresh works and where it can race.",
  "mode": "analyze", "model": "gpt-5.6-luna", "effort": "light",
  "relevant_files": ["src/auth/session.ts"] }

Implementación difícil, máximo razonamiento, con ámbito estricto:

{ "tool": "codex_run",
  "goal": "Make the uploader retry 502s with exponential backoff.",
  "mode": "implement", "model": "gpt-5.6-sol", "effort": "max",
  "allowed_paths": ["src/upload.ts", "tests/upload.test.ts"],
  "no_touch": ["src/auth"],
  "contract": "export function upload(f: File): Promise<Result>",
  "acceptance_criteria": ["Retries up to 3 times", "Existing callers unchanged"],
  "tests": ["npm test -- upload"] }

Dos trabajadores de Codex en ámbitos disjuntos — estos se ejecutan concurrentemente:

{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-sol",
  "effort": "high", "allowed_paths": ["src/api"], "goal": "..." }
{ "tool": "codex_run", "mode": "implement", "model": "gpt-5.6-luna",
  "effort": "medium", "allowed_paths": ["src/ui"], "goal": "..." }

Antigravity para trabajo mecánico barato:

{ "tool": "antigravity_run", "goal": "Summarise every exported symbol in src/lib.",
  "mode": "analyze", "model": "Gemini Flash 3.7", "effort": "light" }

{ "tool": "antigravity_run", "goal": "Build the settings page from design.png.",
  "mode": "implement", "model": "Gemini Flash 3.7", "effort": "high",
  "allowed_paths": ["src/pages/settings"] }

Concurrencia y ámbito de archivos

• implement requiere allowed_paths. Las rutas se normalizan contra la raíz del proyecto; cualquier cosa que escape de ella (.., otras unidades, rutas absolutas en otro lugar) se rechaza antes de que un proceso se inicie.

• Los trabajos implement activos mantienen sus ámbitos de escritura en memoria. Un nuevo trabajo cuyos ámbitos se superponen con uno activo se rechaza con scope_conflict. Los ámbitos disjuntos se ejecutan en paralelo — el trabajo no relacionado nunca se serializa.

• analyze y review no reservan nada: nunca bloquean, y nunca son bloqueados.

Limitación V1: detección, no aislamiento

La protección de ámbito de archivos detecta e informa violaciones; no aísla a cada trabajador en su propio árbol. Un trabajador de implement de Codex se ejecuta con workspace-write en todo el proyecto, así que puede escribir fuera de sus allowed_paths — AgentBridge listará cada uno de esos archivos en scope_violations, degradará el estado de success, y te lo dirá claramente.

Nada se revierte automáticamente. Revertir un archivo que ya fue modificado antes de que el trabajador comenzara destruiría tu trabajo existente (o el de Claude). La detección más un informe honesto es el contrato V1; el aislamiento con git-worktree está deliberadamente fuera de alcance.

La atribución es cuidadosa con el estado preexistente: los archivos que ya estaban sucios antes de una ejecución y son byte-idénticos después nunca se culpan al trabajador. La comparación usa estado de porcelain más hash de contenido, y los archivos commiteados se detectan mediante un diff de movimiento de HEAD.

Seguridad

• Los procesos se generan con arrays de argumentos y shell: false — nunca una cadena de comando interpolada. Los metacaracteres de shell en los argumentos permanecen literales.

• Los lanzadores .cmd/.ps1 de Windows (que Node se niega a generar sin un shell) se resuelven a su script de entrada real de Node y se ejecutan como node <script>, así que shell: true nunca es necesario.

• Los prompts van a Codex a través de stdin; los prompts de Antigravity demasiado grandes se escriben en un archivo temporal y se referencian por ruta. Ninguno puede alcanzar el límite de 32 767 caracteres de la línea de comandos de Windows.

• tests es contexto para el trabajador. AgentBridge nunca lo ejecuta, y no hay ningún argumento MCP en ningún lugar que se convierta en un comando que AgentBridge ejecute.

• El path traversal fuera de la raíz del proyecto se rechaza.

• Los timeouts matan todo el árbol de procesos: taskkill /T /F en Windows, y en POSIX un SIGTERM al grupo de procesos que escala a SIGKILL después de un período de gracia de 3 segundos. La escalada sobrevive deliberadamente a la salida del hijo directo, ya que es exactamente cuando los descendientes pueden seguir ejecutándose. Esto es de mejor esfuerzo — Node no expone un Job Object de Windows, así que si taskkill mismo no puede iniciarse, solo se puede alcanzar al hijo directo.

• Los buffers de salida están limitados (8 MB por flujo) y UTF-8 se decodifica solo después del reensamblaje, así que los caracteres multibyte nunca se dividen.

• Los logs registran solo metadatos de trabajos. Nunca tokens, nunca el entorno, y prompts/salidas solo cuando AGENTBRIDGE_DEBUG=1.

• De lo que AgentBridge no te protege: el trabajador es un agente de codificación real que se ejecuta con tus permisos. En modo implement puede ejecutar comandos del repositorio a través de su propio tooling. Limita tus allowed_paths en consecuencia.

Verificación

AgentBridge ejecuta las comprobaciones del propio proyecto después de que un trabajador sale, fuera de cualquier sandbox, y devuelve la salida real en verification:

"verification": [
  { "command": "npm run typecheck", "ok": true,  "exit_code": 0, "timed_out": false, "duration_ms": 4120, "output_tail": "..." },
  { "command": "npm run test",      "ok": false, "exit_code": 1, "timed_out": false, "duration_ms": 8830, "output_tail": "..." }
]

• verify_commands — ejecuta exactamente estos, en cualquier modo.

• Omitido en modo implement — AgentBridge lee package.json y ejecuta los scripts typecheck y test si existen. Nunca ejecuta build, dev, o start por iniciativa propia; pídelos explícitamente.

• skip_verification: true — no ejecuta nada, y confía en el relato del trabajador.

Los comandos se ejecutan sin shell, así que |, &&, ;, > y backticks fuera de comillas se rechazan en lugar de ejecutarse a medias. Una comprobación fallida establece error: "verification_failed" y degrada un success a partial, así que un trabajador que afirma tests en verde no puede superar a los propios tests.

tests_or_checks_run y test_results informan de lo que AgentBridge realmente ejecutó siempre que ocurrió la verificación; recurren a las afirmaciones del propio trabajador solo cuando no fue así.

Debido a que los comandos provienen del repositorio, un brief que nombre al runner equivocado no puede hacer que AgentBridge lo ejecute: un repo cuyo script de test es node --import tsx --test se comprueba con eso, diga lo que diga el brief.

Variables de entorno

AGENTBRIDGE_CODEX_SANDBOX=auto usa read-only para analyze/review y workspace-write para implement — excepto que en Windows un trabajador de Codex con sandbox no puede capturar la salida de un subproceso (spawn EPERM en stdio con pipe), que es lo que hacen los scripts de npm, los runners de tests y los bundlers — así que puede leer y editar pero nunca ejecutar un runner de tests, un type checker o un build. Esa es una limitación de Codex sin perilla de configuración, así que los trabajos de implement recurren a danger-full-access una vez que un sondeo de una sola vez lo confirma, y lo indican en warnings. Analyze y review mantienen su límite read-only impuesto. En Windows, si una ejecución falla con el helper de sandbox roto (helper_unknown_error: apply deny-read ACLs), AgentBridge reintenta ese trabajo una vez con danger-full-access, recuerda el veredicto durante el resto del proceso, y adjunta un warning a cada resultado afectado diciendo que el límite no se impuso. Nada más desencadena ese recurso, y reiniciar AgentBridge reintenta el sandbox real — así que una versión corregida de Codex lo restaura automáticamente. macOS y Linux nunca sondean, reintentan, ni recurren.

Los logs son una línea JSON por trabajo: timestamp, id del trabajo, proveedor, modelo, esfuerzo, modo, proyecto, duración, código de salida, categoría de error.

Solución de problemas

executable_not_found — la CLI no está en el PATH que Claude Code exporta a los procesos hijos. Confírmalo con codex --version / agy --version en la misma shell, o establece AGENTBRIDGE_CODEX_BIN / AGENTBRIDGE_AGY_BIN.

authentication_required — tu sesión de CLI caducó. Arrégralo en una terminal: codex login para Codex, o inicia sesión de nuevo con agy. AgentBridge deliberadamente no tiene forma de reparar esto: no toca credenciales.

requested_model_unavailable — la lista de modelos cambió, o la CLI instalada nunca ofreció ese modelo. Ejecuta bridge_status (o agy models) para ver qué se ofrece realmente; los details del error ya lo contienen. AgentBridge falla aquí a propósito en lugar de ejecutar silenciosamente un modelo diferente. Si un proveedor renombró un id de modelo, añade el nuevo id a la lista de candidatos de esa etiqueta en src/models/antigravity.ts (o a CODEX_MODELS en src/models/codex.ts), y luego recompila.

output_parse_failed — la CLI cambió la forma de su salida legible por máquina. Comprueba details.stdout_head en el resultado y luego compara con parseCodexEvents / parseAgyOutput.

Después de una actualización de la CLI — vuelve a ejecutar las pruebas y luego la comprobación de humo en vivo:

SMOKE_LIVE=1 node scripts/smoke.mjs

Eso impulsa una sesión MCP real y ejecuta la configuración más económica de cada worker. Sin SMOKE_LIVE=1 solo realiza el handshake y bridge_status, sin consumir nada.

files_changed siempre está vacío — el directorio del proyecto no está dentro de un árbol de trabajo de git. La advertencia en el resultado lo indica. La verificación de cambios necesita git.

No aparece nada bajo /mcp — comprueba que la ruta registrada apunta a dist/index.js (compilado, no src/), y reinicia Claude Code después de una recompilación.

Diseño

src/
  index.ts               stdio entry point
  server.ts              MCP server, tool schemas, dispatch
  config.ts              project-dir resolution, timeout clamping
  logging.ts             JSONL job log (stderr only, never stdout)
  parse.ts               worker-envelope parsing, summary capping
  types.ts
  cli/
    resolve.ts           PATH lookup + Windows shim unwrapping
    detect.ts            version probes, agy model listing, auth heuristics
    codex-catalogue.ts   zero-inference Codex model availability + effort capability
    codex-sandbox.ts     sandbox policy decision and helper-failure detection
  models/
    codex.ts             effort map, argv construction
    antigravity.ts       logical→real model resolution, argv construction
  process/
    runner.ts            shell-free spawn, bounded output, tree kill
  prompts/
    worker-prompt.ts     structured request → worker prompt
  scope/
    paths.ts             normalisation, traversal rejection, overlap
    locks.ts             in-memory write-scope registry
    git-state.ts         snapshot/diff file attribution
  tools/
    codex.ts  antigravity.ts  status.ts  common.ts
tests/                   252 tests, mocked processes, no quota used
scripts/smoke.mjs        real MCP end-to-end check