Chromium Bridge

Chromium Bridge

Versão em russo

Uma ponte entre seu navegador baseado em Chromium e o Claude Code. A extensão oficial "Claude in Chrome" conecta-se em alguns navegadores Chromium (Arc, Vivaldi e outros), mas a automação trava: suas ferramentas são construídas sobre a API de grupos de abas, que está ausente ou quebrada nesses navegadores. Esta ponte usa apenas chrome.tabs / chrome.scripting / chrome.debugger, então funciona em qualquer navegador Chromium que possa carregar uma extensão.

Demo

Claude dirigindo o navegador através da ponte — abrindo a Wikipedia, digitando uma pesquisa e chegando ao artigo:

Arquitetura

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/ — uma extensão MV3: o service worker mantém um WebSocket para o servidor local e executa seus comandos (abas, navegação, texto da página, capturas de tela, cliques, preenchimento de formulários). Clicar no ícone abre o painel de chat (chat.html) — um popup ancorado ao ícone da extensão.
• server/ — um servidor MCP (stdio) que expõe as ferramentas browser_* para o Claude Code e as encaminha para a extensão. Ele aceita conexões WS apenas de uma Origin chrome-extension://… — páginas da web comuns não podem se conectar. Ele também serve o canal /chat: as mensagens do painel passam pelo Claude Agent SDK (autenticado via login do Claude Code) com as mesmas ferramentas browser_*; ferramentas integradas (Bash, Read, etc.) são desabilitadas.

Painel de chat

Um equivalente ao painel lateral "Claude in Chrome": um popup que abre quando você clica no ícone da extensão (sem chrome.sidePanel — não é suportado em todos os lugares). O chat pode ver o navegador: listar abas, ler páginas, tirar capturas de tela e clicar.

A interface do painel está em inglês por padrão e muda para russo automaticamente quando o idioma da interface do navegador é russo. Um seletor de idioma (Auto / English / Русский) na barra inferior substitui a detecção automática; o selo na página segue a mesma escolha.

• O popup fecha quando perde o foco (clicar na página) — isso é comportamento do navegador. O contexto da conversa não é perdido: o painel lembra o session_id e o servidor retoma a conversa via Agent SDK resume. Uma rodada que está em andamento quando o popup fecha é interrompida.
• Só funciona enquanto o servidor está em execução (geralmente uma sessão ativa do Claude Code com o MCP chromium-bridge); caso contrário, o painel mostra "Servidor indisponível".
• Seletor de modelo no cabeçalho do painel: "Padrão" pega o modelo de ~/.claude/settings.json (o que foi definido via /model; as sessões do SDK não leem as configurações do Claude Code por conta própria, o servidor passa o modelo explicitamente), as outras entradas são substituições forçadas. A troca é aplicada em tempo real (setModel) e é lembrada. Substituição na inicialização: CHROMIUM_BRIDGE_CHAT_MODEL=sonnet no ambiente do servidor. Porta: CHROMIUM_BRIDGE_PORT (8929 por padrão) — apenas no lado do servidor; a extensão sempre se conecta à 8929, então alterar a porta também significa editar WS_URL em extension/sw.js e extension/chat.js.
• Histórico de chat: o botão 🕓 no cabeçalho lista conversas passadas (armazenadas no localStorage do painel, as últimas 30).
• Após cada rodada há uma linha de uso: tokens da rodada (↑ entrada incl. cache / ↓ saída) e o custo acumulado da sessão em $ (em assinatura, isso é uma estimativa, não uma cobrança separada).
• Capturas de tela que o agente tira ao longo do caminho são mostradas diretamente no feed do chat (clique para expandir). Elas não são salvas no histórico (o localStorage é finito).
• Você pode colar imagens da área de transferência (Cmd+V no campo de entrada, até 5 por mensagem) — o modelo as vê; apenas um marcador permanece no histórico.
• Modo "Perguntar antes de agir" (caixa de seleção acima do campo de entrada): leitura (abas, texto, capturas de tela, console, rede) prossegue sem perguntas, enquanto ações mutáveis — cliques/digitação/navegação/JS/formulários/fechar abas/envio de arquivos — aguardam um cartão Permitir / Negar. O agente vê uma negação e continua a conversa. A alternância é aplicada imediatamente, sem recriar a sessão (via canUseTool do Agent SDK).

Indicação na página

Quando o Claude age em uma aba (do painel ou do Claude Code):

• um brilho laranja queima ao redor das bordas da página com um selo "✳ Claude está trabalhando…", desaparecendo 2,5s após a última ação;
• um cursor virtual (uma seta laranja) desliza até o ponto da ação e pulsa um anel ao clicar; desaparece após 3,5s de inatividade.

Ambos são ocultados nas capturas de tela para não aparecerem no quadro e confundirem o modelo ao trabalhar com coordenadas. Em páginas onde scripts não podem ser injetados (chrome:// e similares), a indicação é silenciosamente ignorada.

Instalação

1. Extensão: clone este repositório, abra chrome://extensions (no espaço/perfil correto!), ative o "Modo de desenvolvedor", clique em "Carregar sem compactação" e escolha a pasta extension/.

2. Servidor MCP — de qualquer forma:

   • via npm: claude mcp add -s user chromium-bridge -- npx chromium-bridge
   • a partir do clone: cd server && npm install, depois claude mcp add -s user chromium-bridge -- node "$(pwd)/index.mjs".

   Ele carrega no início da sessão — reinicie sua sessão do Claude Code após instalar a extensão.

   Para outros clientes MCP, adicione isso à sua configuração:

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

3. Verifique: a ferramenta browser_status deve retornar {"connected": true}.

Ferramentas

A partir da v0.5.

Ferramenta	O que faz
browser_status	Verifica a conexão com a extensão
browser_tabs_list	Lista abas (id, título, URL)
browser_tab_create / browser_tab_close	Abre / fecha uma aba
browser_navigate	Navega para uma URL; back/forward para histórico
browser_page_text	Título da página, URL e texto visível
browser_computer	Mouse/teclado/capturas de tela via CDP: cliques por coordenadas ou ref, arrastar, passar o mouse, digitar, combinações de teclas, rolar, captura de região com zoom, esperar
browser_read_page	Árvore de acessibilidade com ids de ref (filter=interactive)
browser_find	Encontra elementos por texto/role, retorna refs
browser_form_input	Define valor em input/textarea/select/checkbox/contenteditable por seletor ou ref
browser_click	Clique DOM por seletor CSS (plain .click())
browser_upload_file	Coloca arquivos em um <input type="file">
browser_javascript	Executa JS na página (await suportado)
browser_console_messages	Console da aba (com filtro regex)
browser_network_requests	Requisições de rede da aba (com filtro regex)
browser_resize_window	Tamanho da janela
browser_gif_start / browser_gif_stop	Grava um GIF da aba → arquivo; em gravações longas, a taxa de quadros é reduzida automaticamente pela metade, então o cenário inteiro cabe

Tudo, exceto operações básicas de aba, funciona através de chrome.debugger (CDP): capturas de tela não exigem ativar a aba, cliques são eventos reais de mouse, e console/rede são coletados desde o primeiro toque CDP na aba.

Limitações

• A extensão vive em um perfil de navegador — instale-a no perfil que você deseja automatizar.
• Enquanto o servidor está em execução, seu ping periódico mantém o service worker da extensão acordado. Se o worker estiver adormecido de qualquer forma (por exemplo, o servidor acabou de iniciar), um alarme de keepalive o acorda em ~30 segundos, e o servidor espera até 12 segundos pela reconexão antes de gerar erro.
• Modelo de confiança: o servidor WS escuta em 127.0.0.1 e rejeita conexões cuja Origin não seja chrome-extension://…, o que mantém páginas da web fora. Ele não distingue entre extensões, e um processo local que não seja do navegador pode falsificar o cabeçalho Origin — qualquer coisa que rode como seu usuário é confiável, como na maioria das ferramentas de desenvolvimento locais. Não execute a ponte em uma máquina compartilhada.
• Na primeira ação CDP, o navegador mostra uma barra "Chromium Bridge started debugging this browser" — isso é normal, o depurador é o mecanismo de controle. Fechar a barra desanexa o depurador (a próxima ação o reanexa).
• Console/rede não são gravados retroativamente — apenas depois que a aba é tocada pela primeira vez.
• A porta 8929 é de propriedade de uma sessão: uma segunda sessão paralela do Claude Code não pode iniciar seu próprio servidor WS (a extensão permanece com a primeira).

Licença

MIT