Skip to main content
Glama
README.md
# antigravity-claude-bridge

Usa los modelos de **Claude** (Opus, Sonnet, Haiku) dentro de **Google Antigravity** con tu suscripción de claude.ai (Pro o Max). **No necesitas clave de API ni pagas por tokens.**

Escribes `/claude` en el chat de Antigravity (o eliges el agente `claude`). Claude trabaja sobre tu proyecto: lee, crea y edita archivos, ve las imágenes que pegues y recuerda el proyecto entre sesiones.

> Proyecto comunitario, **no oficial**. No está afiliado a Anthropic ni a Google, ni cuenta con su respaldo. "Claude" es marca de Anthropic y "Antigravity" es marca de Google.

---

## Metas

1. **Que Claude se sienta nativo en Antigravity:** planes, walkthroughs, imágenes, edición de archivos y memoria, como un modelo más de la lista.
2. **Repartir el trabajo entre tus dos suscripciones:** Claude diseña la arquitectura y resuelve lo difícil con tu plan de claude.ai. Gemini te pasa las respuestas, hace lo básico y ejecuta lo que Claude le delega, con tu cuota de Antigravity. Así ningún plan se agota solo.

## Cómo funciona

Funciona en **los dos sentidos**:

```
Antigravity ──► Claude    Tú ──► Antigravity (chat) ──MCP──► el puente ──► claude -p ──► Claude (tu plan de claude.ai)
Claude ──► Antigravity    Tú ──► Claude Code ──MCP──► el puente ──► agy -p ──► Gemini y otros (tu cuota de Antigravity)
```

Los dos lados comparten una carpeta `.ia/` dentro de cada proyecto (ver más abajo).

- **Sin API:** el puente ejecuta el CLI oficial de **Claude Code** (`claude -p`), que usa la sesión que ya iniciaste con tu cuenta de claude.ai. El uso se descuenta de los límites de tu plan, igual que si usaras Claude Code directamente.
- **Memoria por proyecto:** la primera vez, Antigravity le escribe a Claude un resumen detallado del proyecto (`.ia/PROYECTO.md`). En cada llamada el puente agrega la lista de archivos, sus primeras líneas y las últimas entradas de la bitácora.
- **Una sesión por chat:** igual que Antigravity, cada chat empieza con contexto limpio. Cada chat de Antigravity tiene su propia sesión de Claude, con el mismo nombre (por ejemplo «Proyecto_Make_up · Marketing_CoralSkin»), que se retoma aunque reinicies. Las sesiones de un mismo proyecto se enteran de lo que hicieron las otras por `PROYECTO.md` y la bitácora, sin cargar conversaciones ajenas.
- **Imágenes:** si pegas una imagen en el chat, el puente se la pasa a Claude para que la vea.
- **Planes y walkthroughs:** `/claude-plan` hace que Claude prepare un plan sin tocar archivos. Antigravity lo guarda como artifact de plan para que lo revises y comentes, y cuando lo apruebas, Claude lo ejecuta. Después de cada tarea, el puente guarda el walkthrough y lista los archivos que cambiaron.
- **Trabajo en equipo (`/equipo`)**, en los dos entornos y con las mismas etiquetas: cada paso del plan va marcado `[opus]` (lo difícil), `[sonnet]` (implementación media) o `[gemini]` (lo básico, comandos y pruebas), siempre al modelo más barato que lo haga bien.
  - En **Antigravity**, Gemini hace los pasos `[gemini]` con sus herramientas y le pasa a Claude los demás; después verifica el trabajo de Claude y, si falla, le devuelve el error (hasta 2 veces).
  - En **Claude Code**, Opus planea, delega `[sonnet]` a un subagente y `[gemini]` a Gemini Flash (con tu crédito de Antigravity), y luego revisa y prueba todo él mismo.
- **Bitácora compartida:** `.ia/bitacora.md` tiene una entrada corta por trabajo. La escriben Claude vía Antigravity y Gemini vía Claude Code (automático), y Gemini en Antigravity y Claude Code (por sus reglas). Así cualquiera se pone al día leyendo pocas líneas, sin volver a explorar todo el proyecto.

## Requisitos

- macOS o Linux
- [Google Antigravity](https://antigravity.google), con su CLI `agy` (se instala con la app; hace falta para que Claude Code delegue en Gemini)
- [Claude Code](https://claude.com/claude-code) instalado y con sesión iniciada con tu cuenta de claude.ai (`claude`, luego `/login`)
- Python 3.10 o superior y [pipx](https://pipx.pypa.io) (o `uv`)

## Instalación

```bash
pipx install git+https://github.com/JavierC11/antigravity-claude-bridge
antigravity-claude install
```

Después **cierra Antigravity por completo y vuelve a abrirlo**.

`install` configura cinco cosas, y no toca nada que no sea suyo:

| Qué | Dónde |
|---|---|
| Servidor MCP `claude` | `~/.gemini/config/mcp_config.json` (conserva tus otros servidores) |
| Agente `claude` | `~/.gemini/config/agents/claude/agent.md` |
| Comandos `/claude…` | `~/.gemini/config/global_workflows/` |
| Reglas para `@claude` y la bitácora | Un bloque marcado al final de `~/.gemini/GEMINI.md` |
| Reglas de la carpeta `.ia/` para Claude Code | Un bloque marcado al final de `~/.claude/CLAUDE.md` |
| Servidor MCP `antigravity` en Claude Code (Claude → modelos de Antigravity) | Registro de usuario de Claude Code (`claude mcp add -s user`) |
| `/equipo` y el subagente `sonnet-worker` para Claude Code | `~/.claude/commands/` y `~/.claude/agents/` |

Si vienes de la versión 0.2, `install` también **migra** tu memoria a la carpeta `.ia/` de cada proyecto (con copia de seguridad en `~/.antigravity-claude/respaldo-migracion-<fecha>`). También puedes ejecutar `antigravity-claude migrar`.

Antes de modificar un archivo guarda una copia `*.bak-<fecha>`.

Para comprobar que todo está bien:

```bash
antigravity-claude doctor          # revisa la instalación sin gastar uso
antigravity-claude doctor --live   # además hace una consulta real a Claude
```

## Uso en Antigravity

| Escribe en el chat | Qué hace |
|---|---|
| `/claude <pedido>` | Claude (modelo por defecto) hace el pedido en el proyecto abierto |
| `/claude-plan <pedido>` | Claude prepara un plan sin tocar archivos. Lo revisas y comentas, y luego dices "ejecútalo" |
| `/equipo <pedido>` | Trabajo en equipo: Claude planea y asigna cada paso. Claude hace los pasos `[opus]` (lo difícil) y `[sonnet]` (lo medio) y Gemini los `[gemini]` (lo básico, comandos y pruebas). Gemini verifica el trabajo de Claude. `/equipo` sin texto continúa el plan pendiente |
| `/claude-opus <pedido>` | Igual, con Claude Opus |
| `/claude-sonnet <pedido>` | Igual, con Claude Sonnet (más rápido) |
| `/claude-haiku <pedido>` | Igual, con Claude Haiku (el más rápido, para cosas simples) |
| `/claude-sync` | Actualiza el resumen del proyecto que Claude recuerda |
| `/claude-projects` | Lista los proyectos que Claude recuerda |
| `@claude <pedido>` | Lo mismo que `/claude`, escrito como mensaje normal |
| Agente **claude** | Si tu versión de Antigravity permite elegir agente, todo lo que escribas va a Claude |

Ejemplos:

```
/claude explícame qué hace este proyecto
/claude agrega manejo de errores a utils.py
/claude-sonnet ¿qué le falta a este README?
/claude [pegas una captura] haz que la pantalla se vea como esta imagen
```

### En Claude Code (Claude → modelos de Antigravity)

Después de `install`, reinicia Claude Code. Tienes:

| Qué | Para qué |
|---|---|
| `/equipo <pedido>` | Opus planea y reparte: `[opus]` él mismo, `[sonnet]` al subagente `sonnet-worker`, `[gemini]` a Gemini Flash. Luego revisa y prueba |
| `gemini_task` | Gemini edita archivos del proyecto (modelo por defecto `gemini-3.8-flash-medium`) y devuelve los archivos cambiados |
| `gemini_ask` | Gemini analiza o responde sin tocar archivos |
| `gemini_models` | Lista los modelos de Antigravity que puedes usar |

El trabajo de Gemini sale de tu cuota de Antigravity, no del plan de Claude.

### Sesiones y chats desde la terminal

```bash
antigravity-claude sesiones [proyecto]       # chats de Antigravity y su sesión de Claude
antigravity-claude resume <proyecto> [chat]  # abre en Claude Code la sesión de ese chat
antigravity-claude migrar                    # pasa datos de la versión 0.2 a .ia/
```

Las sesiones del puente no salen en la lista de `/resume` de Claude Code (son automáticas), por eso existe `resume`.

### Desde la terminal (Antigravity CLI)

```bash
agy --agent claude                       # sesión interactiva con Claude
agy --agent claude -p "crea un PLAN.md"  # un pedido y termina
```

## Herramientas MCP

Las usa Antigravity; normalmente no hace falta llamarlas a mano.

| Herramienta | Para qué |
|---|---|
| `sync_project(name, project_dir, summary)` | Registra o actualiza un proyecto con su resumen. Si la carpeta no existe, la crea |
| `list_projects()` | Proyectos que Claude conoce |
| `claude_task(task, project, model?, images?, last_upload?, nueva_sesion?, chat?)` | Claude lee, crea y edita archivos **solo** dentro del proyecto. Guarda `.ia/walkthrough.md` y lista los archivos cambiados |
| `claude_plan(task, project, model?, images?, last_upload?, chat?)` | Plan de implementación sin modificar archivos. Se guarda en `.ia/plan.md` |
| `ask_claude(prompt, project?, model?, images?, last_upload?, continuar?)` | Pregunta. Con `project` puede **leer** los archivos, pero no modificarlos |
| `review_code(code, focus?, model?)` | Revisión de un fragmento de código |

## Configuración

Variables de entorno que puedes poner en el bloque `env` del servidor `claude` dentro de `mcp_config.json`:

| Variable | Por defecto | Para qué |
|---|---|---|
| `CLAUDE_MODEL` | `opus` | Modelo por defecto (`opus`, `sonnet`, `haiku` o un id completo). También: `antigravity-claude install --model sonnet` |
| `CLAUDE_TASK_TOOLS` | `Read,Edit,Write,Glob,Grep` | Herramientas de Claude en `claude_task`. Agrega `Bash` solo si quieres que ejecute comandos |
| `CLAUDE_TIMEOUT` | `600` | Segundos máximos por pregunta |
| `CLAUDE_TASK_TIMEOUT` | `1800` | Segundos máximos por tarea |
| `CLAUDE_UPLOAD_MAX_AGE` | `1800` | Antigüedad máxima (segundos) de la imagen pegada que se adjunta con `last_upload` |
| `CLAUDE_BIN` | el `claude` del PATH | Ruta a Claude Code |
| `CLAUDE_BRIDGE_HOME` | `~/.antigravity-claude` | Índice de proyectos y copias de la migración |
| `AGY_MODEL` | `gemini-3.8-flash-medium` | Modelo por defecto de `gemini_task` / `gemini_ask` |
| `AGY_TIMEOUT` | `900` | Segundos máximos por llamada a Gemini |
| `AGY_BIN` | el `agy` del PATH | Ruta al CLI de Antigravity |

## Archivos que aparecen en tu proyecto

Todo lo compartido vive en una sola carpeta oculta, `<proyecto>/.ia/`, que leen Antigravity, el puente y Claude Code:

| Archivo | Qué es | ¿Va a git? |
|---|---|---|
| `.ia/PROYECTO.md` | Conocimiento del proyecto (como los Knowledge Items de Antigravity). Lo escribe `/claude-sync` | Sí |
| `.ia/bitacora.md` | Una entrada corta por cada trabajo, de Claude, Gemini o Claude Code | Sí |
| `.ia/plan.md` | El último plan (con pasos `[opus]`/`[sonnet]`/`[gemini]`) | Sí |
| `.ia/walkthrough.md` | El resumen de la última tarea de Claude | Sí |
| `.ia/sesiones.json` | Qué chat de Antigravity usa qué sesión de Claude y de Gemini | No (`.ia/.gitignore`) |
| `.ia/sesiones/*.md` | Historial completo de cada chat | No |

Las carpetas propias de cada herramienta (`~/.claude/projects`, `~/.gemini/antigravity`) no se tocan.

El resumen de cada entrada lo escribe Claude en la última línea de su respuesta (`RESUMEN: …`). El puente la quita antes de mostrarte la respuesta, así que no gasta una llamada extra.

## Seguridad

- Claude solo puede tocar archivos **dentro de la carpeta del proyecto**. El puente rechaza tu carpeta personal y la raíz del disco.
- **No ejecuta comandos de terminal** salvo que agregues `Bash` a `CLAUDE_TASK_TOOLS`.
- Las ediciones se aplican **sin pedir confirmación**, porque Antigravity no tiene forma de preguntarte. Usa git para revisar y deshacer cambios.
- `ask_claude` y `review_code` sin proyecto no ven ningún archivo tuyo.
- **Gemini es más permisivo que Claude.** `gemini_task` (Claude Code → Antigravity) usa el modo `accept-edits` de `agy`: edita archivos y **puede ejecutar comandos de terminal sin pedir confirmación** (en las pruebas ejecutó `pytest`). El puente solo lo lanza dentro de la carpeta del proyecto; no verificamos que `agy` lo limite a esa carpeta. Usa git y revisa los cambios que te lista.
- El puente quita `ANTHROPIC_API_KEY` del entorno de Claude, para que nunca cobre por API por accidente.

## Limitaciones

- **No aparece en el selector de modelos de Antigravity.** Esa lista la controla Google y no admite modelos propios. Por eso se usa con comandos, el agente o `@claude`.
- **Gemini sigue siendo el intermediario.** Recibe tu mensaje y llama a Claude. Las instrucciones le piden mostrar la respuesta de Claude tal cual, pero a veces la resume o la reformula. La respuesta original siempre está en el detalle de la llamada a la herramienta.
- **Elige un intermediario barato.** El modelo que tengas elegido en Antigravity solo pasa los mensajes, pero gasta tu cuota de Antigravity. Lo recomendable es **Gemini Flash**: es rápido, tiene cuota aparte y en las pruebas pasó las respuestas sin cambiarlas. En el CLI: `agy --agent claude --model gemini-3.8-flash-low`.
- **Imágenes:** funciona con las que pegas en el chat (`last_upload`) o con rutas de archivo. Si Antigravity no avisa que hay imagen, pide "pásale la imagen a Claude".
- **El reparto de `/equipo` en Antigravity depende de Gemini.** El puente no orquesta nada: Gemini sigue las instrucciones del comando. Si se salta un paso o no pasa el id del chat (`chat`), el puente usa la sesión «general» del proyecto.
- **Las sesiones del puente no salen en `/resume` de Claude Code** (son automáticas). Se abren con `antigravity-claude resume`.
- **Límites del plan:** si agotas los límites de tu suscripción, Claude devolverá un error hasta que se renueven.
- **Política de uso:** según la [ayuda de Claude](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan) (noviembre de 2026), `claude -p` con sesión de suscripción usa los límites de tu plan. Anthropic puede cambiar estas condiciones; revísalas y cumple sus términos.

## Problemas comunes

| Síntoma | Solución |
|---|---|
| `Not logged in` | Abre una terminal, ejecuta `claude` y usa `/login` |
| Antigravity no muestra el servidor `claude` | Reinicia Antigravity del todo y ejecuta `antigravity-claude doctor` |
| `El Python configurado ya no existe` | Ejecuta `antigravity-claude install` de nuevo |
| Claude no ve la imagen | Pídele a Antigravity que use `last_upload`, o pásale la ruta del archivo |
| Respuestas cortadas por tiempo | Sube `CLAUDE_TASK_TIMEOUT` (Claude) o `AGY_TIMEOUT` (Gemini) |
| Claude Code no muestra `gemini_task` ni `/equipo` | Reinicia Claude Code, revisa `claude mcp list` y ejecuta `antigravity-claude doctor` |
| `no se encontro el CLI de Antigravity (agy)` | Instala/actualiza Antigravity o define `AGY_BIN` con la ruta de `agy` |
| Un chat de Antigravity no encuentra su carpeta | Moviste o renombraste la carpeta. Ábrela de nuevo en Antigravity; `antigravity-claude sesiones` avisa de las rutas que ya no existen |

## Desinstalar

```bash
antigravity-claude uninstall          # quita servidor, agente, comandos y reglas
antigravity-claude uninstall --purge  # además borra la memoria de proyectos
pipx uninstall antigravity-claude-bridge
```

## Desarrollo

```bash
git clone https://github.com/JavierC11/antigravity-claude-bridge
cd antigravity-claude-bridge
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

## Licencia

MIT