Async Parallel Antigravity for Codex & Claude Code

Ejecuta sesiones paralelas, reanudables y operables por humanos de Antigravity CLI desde Codex, Claude Code o cualquier agente compatible con MCP.

GitHub

Documentación

codex-agy-bridge

Ejecuta Antigravity desde un harness de agente como sesiones agy duraderas, paralelas y operables por humanos a través de MCP.

codex-agy-bridge envuelve la CLI oficial de Antigravity con un plano de control MCP reanudable. Los harnesses de agentes como Codex, Claude Desktop, o tu propio cliente MCP basado en GPT/Claude pueden iniciar ejecuciones agy, esperar eventos dispersos, adjuntar una terminal real, enviar entrada protegida, cancelar de forma segura, continuar conversaciones exactas y recopilar resultados finales más tarde mediante run_id.

Instalación Rápida

Requisitos previos:

Codex CLI para el comando siguiente, u otro harness local compatible con MCP stdio
La CLI oficial de Antigravity (agy), ya autenticada localmente
uv / uvx
tmux en macOS:

brew install tmux

Verifica los comandos requeridos:

codex --version
agy --version
agy models
uvx --version
tmux -V

Autenticación del Día 0

agy --version solo demuestra que el binario existe. Antes de agregar el servidor MCP, ejecuta agy models; si Antigravity te pide iniciar sesión o informa que no has iniciado sesión, inicia una sesión visible y completa el flujo de navegador/inicio de sesión:

agy --prompt-interactive "Authenticate Antigravity and then exit."
agy models

Después de que agy models tenga éxito, instala o reinicia el servidor MCP. Si una ejecución del puente aún encuentra autenticación, agy_run_start devuelve status="auth_required" y abre una sesión de autenticación visible de agy por defecto. Completa el inicio de sesión allí y luego inicia una nueva ejecución. También puedes usar agy_run_observe(view="terminal") o agy_admin(action="doctor") para inspeccionar el estado de autenticación requerida.

Instala desde PyPI con la CLI de Codex:

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- "$(command -v uvx)" codex-agy-bridge@latest

Reinicia el harness y luego verifica en Codex si usaste el comando anterior:

codex mcp get codex-agy-bridge
codex mcp list

Elimínalo con:

codex mcp remove codex-agy-bridge

Para Claude Desktop o un cliente MCP personalizado, usa la misma forma de comando stdio: uvx codex-agy-bridge@latest con AGY_CMD configurado al ejecutable autenticado agy.

Qué Lo Hace Diferente

Sesiones Antigravity paralelas: lanza múltiples ejecuciones independientes agy, cada una con su propio estado duradero, registros, proyección de transcripción y resultado.
Terminales operables por humanos: las ejecuciones en primer plano viven en sesiones persistentes tmux, de modo que Terminal.app puede adjuntarse sin matar al agente.
Control MCP reanudable: las llamadas MCP pueden agotar el tiempo, el harness puede reiniciarse y la ejecución aún puede observarse más tarde mediante run_id.
Orquestación de objetivos: crea un objetivo, inicia objetivos nombrados con paralelismo limitado e inspecciona todo el lote como un esfuerzo coordinado.
Eventos de activación dispersos: agy_run_wait realiza sondeos cortos de ciclo de vida, atención, progreso y eventos de terminal sin spam de sondeo de transcripción.
Entrada protegida: agy_run_input puede rechazar escrituras obsoletas cuando los cursores de eventos o transcripción cambiaron después de que el llamador observó la ejecución.
Observabilidad consciente de trayectoria: se exponen resúmenes de transcripción limitados y evidencia de terminal sin razonamiento privado del modelo.
Higiene operativa: los inicios activos duplicados se deduplican, los grupos de procesos se cancelan de forma segura y los artefactos de resultados completados se conservan.

Detalles de Instalación

Si Eres Un Agente Leyendo Esto

Ayuda al usuario a instalarlo; no modifiques su máquina silenciosamente.

Verifica primero los requisitos previos:

command -v codex
command -v agy
command -v uvx
command -v tmux
agy --version
agy models

Si falta algo, pregunta antes de instalarlo.
Si agy models informa un error de autenticación, ayuda al usuario a completar el flujo de autenticación del Día 0 anterior antes de agregar el servidor MCP.
Luego ejecuta:

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- "$(command -v uvx)" codex-agy-bridge@latest

Verifica:

codex mcp get codex-agy-bridge
codex mcp list

Dile al usuario que reinicie su harness de agente para que se carguen las nuevas herramientas MCP.

PyPI

El comando de Instalación Rápida almacena una definición de servidor MCP stdio. Cuando el harness del agente inicia el servidor, uvx resuelve codex-agy-bridge@latest desde PyPI, lo instala en un entorno aislado en caché y ejecuta el script de consola codex-agy-bridge. AGY_CMD fija el puente al ejecutable agy ya instalado y autenticado del usuario.

No reemplaces $ o $(...) manualmente en el comando. En shells POSIX, $(command -v agy) y $(command -v uvx) se expanden a rutas absolutas de ejecutables.

GitHub

Usa esto cuando quieras la versión del repositorio directamente:

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- uvx --from git+https://github.com/varadfromeast/codex-agy-bridge \
  codex-agy-bridge

Desarrollo Local

git clone https://github.com/varadfromeast/codex-agy-bridge.git
cd codex-agy-bridge
uv sync --extra dev

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- uv --directory "$PWD" run codex-agy-bridge

Cómo Funciona

flowchart LR
  H["Agent harness<br/>(Codex, Claude, custom MCP client)"]
  M["codex-agy-bridge<br/>MCP stdio server"]
  S["Durable control plane<br/>runs, goals, events, results"]
  W["Detached run supervisor"]
  A["Antigravity CLI<br/>agy"]
  T["Persistent tmux session<br/>human attach/input"]
  L["Local Antigravity<br/>trajectory files"]

  H <-->|"MCP tools"| M
  M <--> S
  S --> W
  W --> A
  W <--> T
  A --> L
  W -->|"bounded transcript projection"| S
  T -->|"terminal logs and attention prompts"| S

El puente mantiene el servidor MCP receptivo mientras los supervisores separados poseen los procesos de larga duración agy. El estado y los eventos se persisten localmente, por lo que una ejecución puede continuar después de que la llamada MCP original regrese. Para el modelo de proceso más profundo, consulta docs/ARCHITECTURE.md. Para la visión del bucle de control MCP, consulta docs/MCP_VISION.md.

Herramientas MCP

Herramienta	Propósito
`agy_run_start`	Iniciar, continuar o abrir una ejecución interactiva en primer plano
`agy_run_wait`	Sondeo corto hasta que las ejecuciones seleccionadas emitan eventos de activación dispersos
`agy_run_observe`	Leer vistas completas, de estado, transcripción o terminal sin procesar
`agy_run_input`	Enviar entrada con precondiciones opcionales de evento/transcripción
`agy_run_cancel`	Cancelar una ejecución activa
`agy_run_result`	Leer metadatos de resultado final o fragmentos de resultado limitados
`agy_goal`	Crear objetivos, iniciar metas y leer estado agregado
`agy_admin`	Leer diagnósticos, modelos, complementos, validación y registro de cambios

Flujo típico:

agy_run_start -> agy_run_wait -> agy_run_observe -> agy_run_result

En Codex MCP, las herramientas pueden exponerse con el prefijo del servidor, por ejemplo codex_agy_bridge_agy_run_wait. Las respuestas de ejecución incluyen argumentos exactos wait_call; ten en cuenta que agy_run_wait siempre toma run_ids: ["..."], incluso para una sola ejecución. Las condiciones de espera admitidas son any_attention, any_terminal, all_terminal, any_event y los alias attention, terminal, finished, finish, complete, completed, result, all_finished, all_complete y all_completed.

Usa agy_goal cuando el harness deba dividir el trabajo en objetivos nombrados con un objetivo compartido y paralelismo limitado.

Configuración

Variable	Predeterminado	Propósito
`AGY_CMD`	`agy` en `PATH`	Ejecutable exacto de Antigravity
`AGY_BRIDGE_STATE_DIR`	`~/.local/state/codex-agy-bridge`	Estado duradero de ejecución y objetivos
`AGY_BRIDGE_AGY_ROOT`	`~/.gemini/antigravity-cli`	Conversaciones y trayectorias de Antigravity
`AGY_BRIDGE_MAX_PARALLEL`	`50`	Límite global de ejecuciones concurrentes
`AGY_BRIDGE_COMPLETION_STABILITY_SECONDS`	`150`	Tiempo que un marcador final debe permanecer estable
`AGY_BRIDGE_MCP_WAIT_SLICE_SECONDS`	`120`	Máximo de segundos que una llamada MCP `agy_run_wait` bloquea antes de devolver una instantánea para que las pasarelas no agoten el tiempo

El estado de ejecución sobrevive a los reinicios del servidor MCP bajo ~/.local/state/codex-agy-bridge/.

Estado y Riesgo

Este proyecto es experimental. Actualmente apunta a Python 3.11+, macOS, tmux y comandos y archivos de trayectoria compatibles con Antigravity CLI 1.0.8.

Antigravity es una CLI agéntica. Puede leer y escribir archivos, ejecutar comandos y acceder a la red con los privilegios del usuario actual. Este puente no es un sandbox ni un límite de seguridad.

El puente siempre habilita la política peligrosa de omisión de permisos de Antigravity para que las ejecuciones desatendidas no se detengan en los avisos de aprobación de la CLI. Cualquier entrada dangerously_skip_permissions=false es rechazada; el único valor permitido es true. sandbox=true y additional_directories son sugerencias de política de la CLI, no contención del sistema de archivos.

El puente no lee ni copia las credenciales OAuth de Antigravity. Invoca el binario agy instalado y lee metadatos locales ordinarios de conversación y archivos de trayectoria.

Desarrollo

git clone https://github.com/varadfromeast/codex-agy-bridge.git
cd codex-agy-bridge
uv sync --extra dev
uv run pytest
uv run ruff check .
uv build

Ejecuta el servidor directamente:

uv run codex-agy-bridge

El servidor usa transporte stdio. No imprimas texto de diagnóstico en stdout; corrompería el encuadre MCP.

Publicación

Una etiqueta de versión enviada ejecuta .github/workflows/publish.yml, que verifica versiones, ejecuta comprobaciones, construye distribuciones, publica en PyPI a través de GitHub OIDC, crea una versión de GitHub y publica server.json en el Registro MCP.

Compatibilidad

El lector actual espera JSONL de trayectoria de Antigravity en:

~/.gemini/antigravity-cli/brain/<conversation-id>/
  .system_generated/logs/transcript.jsonl

Si Antigravity se mueve a SQLite o a una API de demonio local, un nuevo adaptador puede reemplazar este lector sin cambiar el contrato de la herramienta MCP.

Licencia

MIT