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

Prueba este MCPPatrocinado

Documentación

codex-agy-bridge

Ejecuta Antigravity desde un entorno 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 entornos de agente 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 entorno local compatible con MCP stdio
La CLI oficial de Antigravity (agy), ya autenticada localmente
uv / uvx
tmux y un lanzador de terminal compatible:

# macOS
brew install tmux

# Debian/Ubuntu Linux (x-terminal-emulator is also supported)
sudo apt install tmux gnome-terminal

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 inicio de sesión/navegador:

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 problemas de autenticación, agy_run_start devuelve status="auth_required" y abre una sesión de autenticación agy visible de forma predeterminada. 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 requerido.

Instala desde PyPI con Codex CLI:

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

Reinicia el entorno 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 agy autenticado.

Qué lo hace diferente

Sesiones Antigravity paralelas: lanza múltiples ejecuciones agy independientes, 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 tmux persistentes, por lo que Terminal.app puede adjuntarse sin matar al agente.
Control MCP reanudable: las llamadas MCP pueden agotar el tiempo de espera, el entorno 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 sondea brevemente eventos de ciclo de vida, atención, progreso y 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: resúmenes de transcripción limitados y evidencia de terminal se exponen 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 mutiles silenciosamente su máquina.

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 entorno 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 entorno del agente inicia el servidor, uvx resuelve codex-agy-bridge@latest desde PyPI, lo instala en un entorno en caché aislado 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 de ejecutable absolutas.

GitHub

Úsalo 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 agy de larga duración. 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 breve 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 condiciones previas opcionales de evento/transcripción
`agy_run_cancel`	Cancelar una ejecución activa
`agy_run_result`	Leer metadatos de resultados finales o fragmentos de resultados limitados
`agy_goal`	Crear objetivos, iniciar objetivos y leer estado agregado
`agy_admin`	Leer diagnósticos, modelos, complementos, validación y registro de cambios

Omite model (o pasa null) para permitir que Agy elija su valor predeterminado: el puente almacena model: null y no envía --model. Esto se aplica a ejecuciones, herramientas de revisión y objetivos, cuyos objetivos heredan la selección de su objetivo. Las selecciones explícitas se validan contra agy models, incluido el valor predeterminado anterior Gemini 3.5 Flash (Medium) del puente; las selecciones desconocidas y vacías se rechazan. El puente nunca sustituye la primera entrada del catálogo. agy_admin(action="models") informa default_model: null y default_model_source: "agy_cli"; esto describe la delegación, no un modelo de proveedor efectivo observado.

Las ejecuciones y objetivos persistidos existentes conservan sus cadenas de modelo y siguen siendo legibles. No se migran silenciosamente a un modelo diferente. Los nuevos lanzamientos desde un objetivo antiguo revalidan su selección y la rechazan si ya no está disponible; crea un nuevo objetivo con un modelo disponible u omite la selección para delegar en Agy. Las ejecuciones reservadas anteriormente conservan su política de comando original. Las nuevas solicitudes delegadas tienen claves de deduplicación distintas de los modelos seleccionados explícitamente. Las versiones anteriores del puente que requieren una cadena de modelo de objetivo no pueden leer objetivos nuevos con modelo nulo; evita degradar con esos objetivos en uso.

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 wait_call exactos; ten en cuenta que agy_run_wait siempre toma run_ids: ["..."], incluso para una sola ejecución. Las condiciones de espera compatibles 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 entorno 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 ejecuciones 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 sola llamada MCP `agy_run_wait` bloquea antes de devolver una instantánea para que las puertas de enlace no agoten el tiempo de espera

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 o Linux con un lanzador de terminal compatible, 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 de omisión de permisos peligrosos de Antigravity para que las ejecuciones desatendidas no se detengan en avisos de aprobación de CLI. Cualquier entrada dangerously_skip_permissions=false se rechaza; el único valor permitido es true. sandbox=true y additional_directories son sugerencias de política de 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 de conversación locales ordinarios 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 marco 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 bajo:

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

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

Licencia

MIT