Agy Bridge

User → Claude Code → agy-bridge (MCP) → agy CLI → Gemini / Claude / GPT-OSS
                   ←                  ←          ←

¿Por qué esto en lugar de claude-to-agy?

	claude-to-agy	agy-bridge
Superficie de herramientas	1 delegate_to_agy genérico	6 herramientas específicas — Claude se auto-enruta de forma fiable
Selección de modelo	ninguno (solo el predeterminado de agy)	enrutamiento por herramienta entre todos los agy models, con detección de disponibilidad y respaldo
Multi-turno	sin estado	continuidad de sesión — follow_up reanuda conversaciones de agy sin reenviar contexto
Seguridad de salida	sin límite	límite de truncamiento configurable protege el contexto de Claude
Sandbox	no	modo --sandbox opcional
Instalación	uvx (Python)	npx (Node) — instalación cero

Requisitos

• Node.js 18+
• CLI de Antigravity (agy) instalada y autenticada
• Claude Code

Instalación

# 1. Register the MCP server (user scope = all projects).
#    add-json bakes in a generous client-side timeout so long analyze_files /
#    delegate calls don't trip Claude Code's tool-call deadline (see Timeouts).
claude mcp add-json -s user agy-bridge \
  '{"command":"npx","args":["-y","agy-bridge"],"timeout":600000}'

# 2. Add delegation rules to your project (or ~/.claude/CLAUDE.md for global)
curl -o CLAUDE.md https://raw.githubusercontent.com/sshahzaiib/agy-bridge/main/CLAUDE.md

El "timeout": 600000 (10 min, milisegundos) es el plazo de llamada de herramienta del lado del cliente — sin él, un analyze_files de arranque en frío (~40–50s) o un delegate largo pueden alcanzar el valor predeterminado de Claude Code y devolver timed out waiting for response mientras la ejecución de agy aún continúa. Si tu cliente no respeta un timeout por servidor, establece la variable de entorno global MCP_TOOL_TIMEOUT=600000 en su lugar. Los detalles y los presupuestos del lado de agy están en Timeouts y cancelación.

Herramientas

Herramienta	Uso para	Enrutamiento de modelo (primero disponible)
analyze_files	Archivos >200 líneas, >3 archivos a la vez, registros, volcados, código generado	Gemini 3.5 Flash (Alto) → Gemini 3.1 Pro (Bajo)
deep_search	Arqueología de git log/diff/blame, búsquedas en todo el repositorio	Gemini 3.5 Flash (Medio) → (Alto)
web_lookup	Documentación, referencias de API, conocimiento externo/actual	Gemini 3.5 Flash (Medio) → (Alto)
adversarial_review	Críticas de planes, revisiones de diseño y código	Gemini 3.1 Pro (Alto) → Claude Opus 4.6 (Pensamiento) → Flash (Alto)
follow_up	Continuar una sesión anterior por session_id — sin reenvío de contexto	hereda la sesión
delegate	Cualquier otra cosa pesada	Gemini 3.5 Flash (Alto)

Todas las herramientas aceptan cwd opcional (raíz del proyecto) y model (nombre exacto de agy models; validado, con modelos disponibles listados en caso de discrepancia).

Cada respuesta termina con un pie de página:

---
[agy-bridge] model: Gemini 3.5 Flash (High) | session: 1f0c…-d4 (use follow_up to continue)

Enrutamiento de modelo

En el primer uso, el puente ejecuta agy models (almacenado en caché durante la vida del proceso) y elige el primer modelo disponible en la cadena de preferencias de la herramienta. Si ninguno está disponible, recurre a AGY_DEFAULT_MODEL, y finalmente al predeterminado de agy. agy ignora silenciosamente los valores desconocidos de --model, por lo que el puente valida los nombres de antemano en lugar de permitir que las solicitudes lleguen al modelo equivocado.

Conmutación por error consciente de cuotas

agy nunca muestra el agotamiento de cuota en modo de impresión — reintenta silenciosamente el 429 hasta su tiempo de impresión, luego sale con 0 y salida vacía, lo que solía parecer un cuelgue indefinido. El puente ahora observa el archivo de registro de cada ejecución (vía --log-file) y en RESOURCE_EXHAUSTED (code 429):

1. mata el grupo de procesos de agy inmediatamente (sin esperar el tiempo de espera),
2. analiza el tiempo de reinicio ("Resets in 4h24m") en un registro de enfriamiento en proceso,
3. reintenta el mismo prompt en el siguiente modelo de la cadena de la herramienta,
4. omite los modelos en enfriamiento en todas las llamadas posteriores hasta que su cuota se reinicie.

Las conmutaciones por error se anotan en el pie de página de la respuesta (failover: <model>: quota exhausted (resets in 4h24m)). Solo cuando todos los candidatos están agotados la llamada falla — en segundos, con los tiempos de reinicio listados — en lugar de colgarse.

Timeouts y cancelación

Cada herramienta tiene su propio timeout predeterminado ajustado a su tarea: web_lookup 120s, deep_search 180s, analyze_files / adversarial_review / follow_up 300s, delegate 600s. Establecer AGY_TIMEOUT explícitamente los anula todos a la vez. Para cambiar una sola herramienta, establece AGY_TIMEOUT_<TOOL_NAME> en su lugar (por ejemplo, AGY_TIMEOUT_DEEP_SEARCH=300); una anulación por herramienta tiene prioridad sobre el AGY_TIMEOUT global y el predeterminado de la herramienta. El conjunto completo de variables por herramienta es AGY_TIMEOUT_ANALYZE_FILES, AGY_TIMEOUT_DEEP_SEARCH, AGY_TIMEOUT_WEB_LOOKUP, AGY_TIMEOUT_ADVERSARIAL_REVIEW, AGY_TIMEOUT_FOLLOW_UP y AGY_TIMEOUT_DELEGATE. La ruta de terminación escala SIGTERM → SIGKILL en todo el grupo de procesos, y el plazo se activa incluso si los procesos auxiliares de agy mantienen abiertos los conductos de salida. Cancelar la llamada de herramienta desde el cliente MCP (por ejemplo, presionando Esc en Claude Code) también mata la ejecución de agy en lugar de dejarla huérfana.

Dos capas de timeout — alinéalas. Los timeouts anteriores son el presupuesto del lado de agy. Tu cliente MCP (Claude Code) tiene su propio timeout de llamada de herramienta separado, y si es más corto que el presupuesto de agy, el cliente se rinde primero — verás Error: timed out waiting for response (nota: el timeout propio de agy-bridge lee agy timed out after Ns en su lugar). El trabajo no se pierde: la sesión de agy persiste, por lo que follow_up con el session_id devuelto recupera el resultado. Pero la solución real es hacer que el cliente espere al menos tanto como agy: el comando de Instalación ya establece un timeout por servidor de 600000ms (limitado solo a la entrada de agy-bridge). Si registraste el servidor sin él, vuelve a ejecutar el comando add-json de Instalación, o establece la variable de entorno global MCP_TOOL_TIMEOUT=600000. Regla general: timeout del cliente ≥ presupuesto de agy.

Latencia esperada. La mayor parte de la "lentitud" percibida es el arranque en frío: la primera llamada en una sesión inicia la CLI de agy y calienta el modelo. Un analyze_files simple sobre 3 archivos mide alrededor de 40–50s en frío (≈46s observados), disminuyendo en llamadas posteriores de la misma sesión. Una primera llamada que también encuentra una cuota 429 tarda más mientras el puente conmuta. Por lo tanto, un timeout de cliente por debajo de ~60s tropezará intermitentemente con arranques en frío incluso para preguntas "simples" — ajústalo generosamente.

Configuración

Todo opcional, mediante variables de entorno:

Variable	Predeterminado	Descripción
AGY_PATH	agy	Ruta al binario de agy
AGY_TIMEOUT	por herramienta	Segundos; anula todos los timeouts por herramienta a la vez (ver arriba), pasado como --print-timeout, aplicado con un margen de terminación de 15s
AGY_TIMEOUT_<TOOL>	por herramienta	Segundos; anula el timeout de una sola herramienta, por ejemplo, AGY_TIMEOUT_DEEP_SEARCH=300. Gana sobre AGY_TIMEOUT
AGY_MAX_OUTPUT_CHARS	50000	Límite de truncamiento para la salida de herramientas
AGY_DEFAULT_MODEL	sin establecer	Modelo de respaldo cuando no hay entrada de cadena disponible
AGY_SKIP_PERMISSIONS	true	Pasa --dangerously-skip-permissions a agy
AGY_SANDBOX	false	Ejecuta agy con --sandbox
AGY_ON_FAILURE	fallback	strict agrega una instrucción a los errores de herramientas fallidas diciendo al agente llamante que no absorba el trabajo él mismo

Comportamiento ante fallos

El puente siempre falla de forma ruidosa: los errores de agy aparecen como errores de herramientas MCP con el stderr real de agy, y el enrutamiento degradado de modelos se anota en el pie de página de la respuesta. Por defecto, el agente llamante (Claude) normalmente hará el trabajo él mismo después de un fallo — visible en la transcripción, pero fácil de dejar de notar en una sesión larga. Establece AGY_ON_FAILURE=strict para agregar una instrucción explícita de "NO realices este trabajo tú mismo — informa el fallo al usuario" a cada error de delegación, para que mantengas el control sobre cuándo se pierden silenciosamente los ahorros de tokens.

Desarrollo

npm install
npm test           # vitest unit tests (exec mocked — no agy needed)
npm run typecheck
npm run build      # tsup → dist/index.js

Contribuyentes

Las contribuciones son bienvenidas — abre un issue o un PR.

Historial de estrellas

Licencia

MIT