Bridge e integración con IDE

Dos sistemas distintos. La integración con IDE conecta la CLI a VS Code y JetBrains en la misma máquina via MCP sobre localhost. El Bridge conecta una instancia de la CLI a claude.ai como frontend web, permitiendo control remoto desde cualquier navegador.

2 sistemas (IDE + Bridge) 2 versiones del protocolo Bridge 15 IDEs JetBrains soportados 3 modos de spawn del Bridge

i Dos sistemas completamente distintos

La integración con IDE es local: CLI y editor en la misma máquina, comunicándose por MCP sobre localhost. El Bridge es remoto: un túnel entre la CLI (en cualquier lugar) y claude.ai (navegador), con el backend de Anthropic en el medio.

Arquitectura

Integración con IDE (local)

VS Code / JetBrains

<─── MCP (SSE/WS) ───>

Claude Code CLI

localhost:puerto — misma máquina

Bridge (remoto)

claude.ai (navegador)

<─── HTTPS/WSS ───>

Backend de Anthropic

<─── SSE/HTTP ───>

Claude Code CLI (worker)

Integración con IDE

IDEs soportados

VS Code / Cursor / Windsurf auto-instalación

Extensión descubierta e instalada automáticamente con code --install-extension anthropic.claude-code-vscode. Comunicación via MCP sobre SSE o WebSocket en localhost.

JetBrains (15 IDEs) instalación manual

IntelliJ IDEA, WebStorm, PyCharm, PhpStorm, RubyMine, CLion, GoLand, Rider, DataGrip, DataSpell, AppCode, Android Studio, Aqua, RustRover, Writerside. El plugin debe instalarse manualmente.

Cómo funciona el descubrimiento

Las extensiones de IDE escriben lockfiles en ~/.claude/ide/<ide-name>-<pid>.lock al arrancar y los eliminan al cerrarse. Claude Code lee estos lockfiles para descubrir los IDEs en ejecución y su información de conexión (puerto, tipo de transporte, token de autenticación).

Tipos de transporte MCP del IDE

// Transporte SSE desde el IDE (lectura via EventSource)
{ type: 'sse-ide', url: 'http://localhost:PUERTO/sse', ideName: 'vscode' }

// Transporte WebSocket desde el IDE
{ type: 'ws-ide', url: 'ws://localhost:PUERTO/ws', ideName: 'vscode', authToken?: 'token' }

Son tipos de transporte internos, no configurables por el usuario. Los configuran automáticamente las extensiones del IDE.

Funcionalidades

Sincronización de edición de archivos

Cuando Claude Code edita un archivo, el IDE recibe una notificación via MCP. El IDE muestra una vista de diff y el usuario puede aceptar o rechazar los cambios en el editor.

Compartición de contexto

El IDE puede enviar texto seleccionado, archivos abiertos y posición del cursor a Claude Code, enriqueciendo su comprensión de lo que está trabajando el usuario.

Vistas de diff

openDiffInIde() abre una vista de diff en el IDE para un archivo concreto. closeDiffTabsInIde() limpia las pestañas cuando se aceptan los cambios.

Canal bidireccional (claude-vscode)

Canal de notificación especial entre la CLI y VS Code. Envía ediciones de archivos, valores de feature flags, eventos de análisis. Recibe cambios de archivos y acciones del usuario.

Sistema Bridge (control remoto)

El Bridge conecta una instancia de la CLI a claude.ai como frontend web. Casos de uso: controlar Claude Code desde cualquier navegador, ejecutarlo en un servidor remoto, gestionar múltiples sesiones, compartir sesiones via códigos QR y URLs.

Dos versiones del protocolo

Versión	Lectura	Escritura	Notas
v1	WebSocket (WSS)	HTTP POST (lote cada 100ms)	Environments API + bucle de polling. Más antiguo y complejo.
v2	SSE stream	HTTP POST (CCRClient)	Creación directa de sesión, más simple. Feature-gated.

Tres modos de ejecución

Modo	Punto de entrada	Descripción
Standalone	claude remote-control / bridgeMain.ts	Proceso dedicado, soporta múltiples sesiones concurrentes
REPL En-proceso	initReplBridge.ts → replBridge.ts	El Bridge corre dentro de una sesión REPL existente
Env-less	remoteBridgeCore.ts	Conexión directa de sesión (protocolo v2)

Modos de spawn (standalone)

Modo	Descripción
single-session	Una sesión en el CWD, el bridge se cierra al terminar
worktree	Servidor persistente, cada sesión recibe un git worktree aislado
same-dir	Servidor persistente, todas las sesiones comparten el CWD

Protocolo de comunicación

Saliente: CLI → claude.ai

Tipo	Descripción
assistant	Respuesta de texto de Claude
result	Resultados de ejecución de herramientas
partial_assistant	Respuestas parciales en streaming
status	Actualizaciones de estado
control_response	Respuesta a una solicitud de control
control_request	Solicitud de control iniciada por la CLI
keep_alive	Ping de keepalive

Entrante: claude.ai → CLI

Tipo	Descripción
user	Mensajes del usuario desde la web
control_request	Solicitud de control iniciada por el servidor
control_response	Respuesta a solicitud de control de la CLI
keep_alive	Ping de keepalive
update_environment_variables	Actualizar variables de entorno (refresco de token)

Subtipos de solicitud de control (selección)

Subtipo	Dirección	Descripción
initialize	Servidor → CLI	Inicializa la sesión, devuelve comandos, modelos, cuenta, PID
interrupt	Servidor → CLI	Interrumpe el turno actual
can_use_tool	CLI → Servidor	Solicita permiso para ejecutar una herramienta (el usuario ve Allow/Deny en el navegador)
set_model	Servidor → CLI	Cambia el modelo de IA
set_permission_mode	Servidor → CLI	Cambia el modo de permisos
mcp_set_servers	Servidor → CLI	Reemplaza los servidores MCP dinámicos
rewind_files	Servidor → CLI	Revierte cambios de archivos
apply_flag_settings	Servidor → CLI	Aplica configuración de feature flags desde el backend
elicitation	Servidor → CLI	Solicita input del usuario para elicitación MCP

Ciclo de vida de la sesión

v1 (Environments API + bucle de polling)

REGISTRO POST /v1/environments/bridge → {environment_id, environment_secret}

POLLING GET /v1/environments/{id}/work/poll cada 2s (o 10 min al alcanzar capacidad)

TRABAJO RECIBIDO Decodifica WorkSecret (JSON base64url): token de sesión, API base URL, fuentes, auth

ACUSE POST /v1/environments/{id}/work/{workId}/ack

SPAWN HIJO claude --print --sdk-url <ws_url> --session-id <id> --replay-user-messages

HEARTBEAT POST /v1/environments/{id}/work/{workId}/heartbeat (auth JWT, sin hit a BD)

FIN POST /v1/sessions/{id}/archive + SIGTERM → 30s gracia → SIGKILL

v2 (sesión directa)

CREAR POST /v1/code/sessions (OAuth) → {session_id, session_url}

JWT POST /v1/code/sessions/{id}/bridge → {worker_jwt, epoch}

CONECTAR SSE GET {sessionUrl}/worker/events/stream — Authorization: Bearer <worker_jwt>

PROCESAR Recibe via SSE, escribe via HTTP POST a {sessionUrl}/worker/events

REFRESCAR POST /v1/code/sessions/{id}/bridge → nuevo worker_jwt (5 min antes de expirar)

Flujo de permisos (remoto)

Cuando la CLI necesita ejecutar una herramienta en modo remoto, envía una solicitud de control can_use_tool al servidor. La web muestra al usuario un diálogo Allow/Deny. La respuesta puede incluir argumentos modificados o nuevas reglas de permisos.

// Respuesta de permiso desde la web
{
  behavior: 'allow' | 'deny',
  updatedInput?: Record<string, unknown>,   // Argumentos modificados
  updatedPermissions?: [                     // Nuevas reglas de sesión
    { tool: 'Bash(rm:*)', behavior: 'deny' }
  ],
  message?: string
}

Autenticación

Orden de resolución del token OAuth

1. Variable de entorno CLAUDE_BRIDGE_OAUTH_TOKEN (solo desarrollo)
2. Token OAuth del keychain del SO
3. Flujo OAuth interactivo via navegador

Refresco del token JWT de sesión

Refresco programado 5 min antes de expirar el JWT
Fallback: refresco cada 30 min si no se puede decodificar el JWT
Nuevo token enviado al proceso hijo via update_environment_variables
Máximo 3 fallos de init consecutivos antes de deshabilitar el Bridge

Cada petición incluye: Authorization: Bearer <oauth_token>, anthropic-version: 2023-06-01, anthropic-beta: environments-2025-11-01. Para el nivel de seguridad ELEVATED: también X-Trusted-Device-Token.

Constantes y timeouts

Constante	Valor	Descripción
Intervalo de polling (inactivo)	2.000ms	v1: frecuencia de comprobación de trabajo nuevo
Intervalo de polling (al límite)	600.000ms (10 min)	v1: intervalo cuando todos los slots están ocupados
SSE delay inicial de reconexión	1.000ms	v2: retardo inicial de reconexión
SSE delay máximo de reconexión	30.000ms	v2: backoff máximo de reconexión
SSE tiempo de abandono	600.000ms (10 min)	v2: dejar de intentar reconexión
SSE timeout de liveness	45.000ms	v2: máximo sin datos antes de reconectar
HybridTransport batch flush	100ms	v1: agrupar mensajes salientes
HybridTransport POST timeout	15.000ms	v1: timeout de HTTP POST
Buffer de refresco de token	5 min	Refrescar JWT antes de expirar
Intervalo de refresco fallback	30 min	Refrescar si no se puede decodificar el JWT
Máx. fallos de init	3	Deshabilitar el Bridge tras 3 fallos consecutivos
Descarte de error del Bridge	10.000ms	Auto-descartar la UI de error
Umbral de reclamación de sesión	5.000ms	Reclamar sesiones inactivas más antiguas que esto
Período de gracia de apagado	30.000ms	Retardo SIGTERM → SIGKILL para procesos hijo

→ Lo que el Bridge permite que la CLI sola no puede

El Bridge convierte Claude Code en un servicio accesible desde la web. Con el modo de spawn worktree, cada sesión remota recibe su propio git worktree aislado, por lo que varios usuarios en paralelo nunca colisionan. El protocolo can_use_tool hace que la web reciba prompts de permiso interactivos completos, incluyendo la capacidad de modificar los argumentos de la herramienta antes de que se ejecute.