Chromium Bridge

Chromium Bridge

Русская версия

Un puente entre tu navegador basado en Chromium y Claude Code. La extensión oficial "Claude in Chrome" se conecta en algunos navegadores Chromium (Arc, Vivaldi y otros), pero la automatización se bloquea: sus herramientas están construidas sobre la API de grupos de pestañas, que falta o está rota allí. Este puente usa solo chrome.tabs / chrome.scripting / chrome.debugger, por lo que funciona en cualquier navegador Chromium que pueda cargar una extensión.

Demo

Claude conduciendo el navegador a través del puente: abriendo Wikipedia, escribiendo una búsqueda y llegando al artículo:

Arquitectura

Claude Code ⇄ (stdio MCP) ⇄ server/index.mjs ⇄ (WebSocket, 127.0.0.1:8929) ⇄ extension in the browser
                                   ⇅ (WebSocket /chat)
                            chat panel (popup on the extension icon)

• extension/ — una extensión MV3: el service worker mantiene un WebSocket hacia el servidor local y ejecuta sus comandos (pestañas, navegación, texto de página, capturas de pantalla, clics, relleno de formularios). Al hacer clic en el icono se abre el panel de chat (chat.html) — un popup anclado al icono de la extensión.
• server/ — un servidor MCP (stdio) que expone las herramientas browser_* a Claude Code y las envía a la extensión. Acepta conexiones WS solo desde un Origin chrome-extension://… — las páginas web normales no pueden conectarse. También sirve el canal /chat: los mensajes del panel pasan por el Claude Agent SDK (autenticado mediante el inicio de sesión de Claude Code) con las mismas herramientas browser_*; las herramientas integradas (Bash, Read, etc.) están deshabilitadas.

Panel de chat

Un equivalente del panel lateral "Claude in Chrome": un popup que se abre al hacer clic en el icono de la extensión (sin chrome.sidePanel — no es compatible en todos los lugares). El chat puede ver el navegador: listar pestañas, leer páginas, tomar capturas de pantalla y hacer clic.

La interfaz del panel está en inglés por defecto y cambia automáticamente a ruso cuando el idioma de la interfaz del navegador es ruso. Un selector de idioma (Auto / English / Русский) en la barra inferior anula la detección automática; la insignia en la página sigue la misma elección.

• El popup se cierra cuando pierde el foco (al hacer clic en la página) — eso es el comportamiento del navegador. El contexto de la conversación no se pierde: el panel recuerda el session_id y el servidor reanuda la conversación a través del Agent SDK resume. Un turno que está en curso cuando el popup se cierra se interrumpe.
• Solo funciona mientras el servidor está en ejecución (normalmente una sesión activa de Claude Code con el MCP chromium-bridge); de lo contrario, el panel muestra "Servidor no disponible".
• Selector de modelo en el encabezado del panel: "Predeterminado" toma el modelo de ~/.claude/settings.json (lo que se haya configurado mediante /model; las sesiones del SDK no leen la configuración de Claude Code por sí mismas, el servidor pasa el modelo explícitamente), las otras entradas son anulaciones forzadas. El cambio se aplica sobre la marcha (setModel) y se recuerda. Anulación al inicio: CHROMIUM_BRIDGE_CHAT_MODEL=sonnet en el entorno del servidor. Puerto: CHROMIUM_BRIDGE_PORT (8929 por defecto) — solo en el lado del servidor; la extensión siempre se conecta a 8929, por lo que cambiar el puerto también implica editar WS_URL en extension/sw.js y extension/chat.js.
• Historial de chat: el botón 🕓 en el encabezado lista conversaciones pasadas (almacenadas en el localStorage del panel, las últimas 30).
• Después de cada turno hay una línea de uso: tokens del turno (↑ entrada incl. caché / ↓ salida) y el costo acumulado de la sesión en $ (en una suscripción esto es una estimación, no una factura separada).
• Las capturas de pantalla que el agente toma en el camino se muestran directamente en el feed del chat (clic para expandir). No se guardan en el historial (el localStorage es finito).
• Puedes pegar imágenes desde el portapapeles (Cmd+V en la entrada, hasta 5 por mensaje) — el modelo las ve; solo queda un marcador en el historial.
• Modo "Preguntar antes de actuar" (casilla sobre la entrada): la lectura (pestañas, texto, capturas de pantalla, consola, red) procede sin preguntas, mientras que las acciones mutantes — clics/escritura/navegación/JS/formularios/ cierre de pestañas/subida de archivos — esperan una tarjeta Permitir / Denegar. El agente ve una denegación y continúa la conversación. El cambio se aplica de inmediato, sin recrear la sesión (a través de canUseTool del Agent SDK).

Indicación en la página

Cuando Claude actúa en una pestaña (desde el panel o desde Claude Code):

• un resplandor naranja arde alrededor de los bordes de la página con una insignia "✳ Claude está trabajando…", que se desvanece 2.5s después de la última acción;
• un cursor virtual (una flecha naranja) se desliza al punto de acción y pulsa un anillo al hacer clic; desaparece después de 3.5s de inactividad.

Ambos están ocultos en las capturas de pantalla para que no aparezcan en el fotograma y confundan al modelo al trabajar con coordenadas. En páginas donde no se pueden inyectar scripts (chrome:// y similares), la indicación se omite silenciosamente.

Instalación

1. Extensión: clona este repositorio, abre chrome://extensions (¡en el espacio/perfil correcto!), habilita "Modo desarrollador", haz clic en "Cargar descomprimida" y elige la carpeta extension/.

2. Servidor MCP — de cualquier manera:

   • vía npm: claude mcp add -s user chromium-bridge -- npx chromium-bridge
   • desde el clon: cd server && npm install, luego claude mcp add -s user chromium-bridge -- node "$(pwd)/index.mjs".

   Se carga al inicio de la sesión — reinicia tu sesión de Claude Code después de instalar la extensión.

   Para otros clientes MCP, agrega esto a tu configuración:

   {
     "mcpServers": {
       "chromium-bridge": {
         "command": "npx",
         "args": ["chromium-bridge"]
       }
     }
   }
   

3. Verifica: la herramienta browser_status debería devolver {"connected": true}.

Herramientas

A partir de v0.5.

Herramienta	Qué hace
browser_status	Verifica la conexión con la extensión
browser_tabs_list	Lista pestañas (id, título, URL)
browser_tab_create / browser_tab_close	Abrir / cerrar una pestaña
browser_navigate	Navegar a una URL; back/forward para el historial
browser_page_text	Título de página, URL y texto visible
browser_computer	Mouse/teclado/capturas de pantalla vía CDP: clics por coordenadas o ref, arrastrar, hover, escribir, combinaciones de teclas, desplazamiento, captura de región con zoom, esperar
browser_read_page	Árbol de accesibilidad con ids de ref (filtro=interactivo)
browser_find	Encuentra elementos por texto/rol, devuelve refs
browser_form_input	Establece el valor de input/textarea/select/checkbox/contenteditable por selector o ref
browser_click	Clic DOM por selector CSS (plain .click())
browser_upload_file	Coloca archivos en un <input type="file">
browser_javascript	Ejecuta JS en la página (await compatible)
browser_console_messages	Consola de pestaña (con un filtro regex)
browser_network_requests	Solicitudes de red de pestaña (con un filtro regex)
browser_resize_window	Tamaño de ventana
browser_gif_start / browser_gif_stop	Graba un GIF de la pestaña → archivo; en grabaciones largas la tasa de fotogramas se reduce automáticamente a la mitad, por lo que todo el escenario cabe

Todo excepto las operaciones básicas de pestañas funciona a través de chrome.debugger (CDP): las capturas de pantalla no requieren activar la pestaña, los clics son eventos reales de mouse, y la consola/red se recopilan desde el primer toque CDP de la pestaña.

Limitaciones

• La extensión vive en un perfil de navegador — instálala en el que quieras automatizar.
• Mientras el servidor está en ejecución, su ping periódico mantiene despierto el service worker de la extensión. Si el worker está dormido de todos modos (por ejemplo, el servidor acaba de iniciarse), una alarma de keepalive lo despierta en ~30 segundos, y el servidor espera hasta 12 segundos por la reconexión antes de dar error.
• Modelo de confianza: el servidor WS escucha en 127.0.0.1 y rechaza conexiones cuyo Origin no sea chrome-extension://…, lo que mantiene fuera a las páginas web. No distingue entre extensiones, y un proceso local que no sea un navegador puede falsificar el encabezado Origin — cualquier cosa que se ejecute como tu usuario es confiable, como con la mayoría de las herramientas de desarrollo locales. No ejecutes el puente en una máquina compartida.
• En la primera acción CDP, el navegador muestra una barra "Chromium Bridge started debugging this browser" — eso es normal, el depurador es el mecanismo de control. Cerrar la barra desconecta el depurador (la siguiente acción lo vuelve a conectar).
• La consola/red no se registran retroactivamente — solo después de que la pestaña se toca por primera vez.
• El puerto 8929 es propiedad de una sesión: una segunda sesión paralela de Claude Code no puede iniciar su propio servidor WS (la extensión se queda con la primera).

Licencia

MIT