agent-chrome
Permite que o Claude Code use uma cópia do seu Chrome conectado no macOS. Um pequeno proxy mantém o pipe de depuração do Chrome, então a janela abre atrás dos seus outros aplicativos e nunca assume o foco. Várias sessões compartilham um único Chrome.
Documentação
agent-chrome
Seu Chrome, atrás do terminal.
O agent-chrome permite que o Claude Code use uma cópia do seu Chrome com sessão iniciada. A janela abre atrás dos seus outros aplicativos, então você continua digitando enquanto o Claude navega como você.
Site Instalar Como funciona Assista ao vídeo de 1:26
Mesmo prompt, duas configurações. O Playwright MCP traz o Chrome para a frente a cada chamada, e o que você digita em seguida vai parar no navegador.
O agent-chrome abre as abas em uma janela vermelha atrás do seu terminal. O foco permanece onde você o deixou.
/plugin marketplace add rav4nn/agent-chrome
Gratuito e de código aberto. Requer macOS, Google Chrome, Node 18.3 ou posterior e Claude Code.
Como se compara
O Playwright headless nunca rouba o foco, mas você não consegue ver o que ele está fazendo. As outras ferramentas mostram uma janela e a trazem para a frente do seu trabalho. O agent-chrome oferece uma janela que você pode observar e a mantém atrás do seu terminal.
| agent-chrome | Playwright MCP headless | Playwright MCP modo extensão | Chrome DevTools MCP configuração padrão | |
|---|---|---|---|---|
| Você pode vê-lo trabalhar Abra a janela a qualquer momento e veja o que o Claude está fazendo, depois ajuste seu prompt ou habilidade. | ✅ | ❌ | ✅ | ✅ |
| Você pode assumir um login Quando o Claude parar em um login, um código 2FA ou um CAPTCHA, clique e finalize você mesmo. | ✅ | ❌ | ✅ | ✅ |
| Você continua digitando O navegador nunca pula para a frente do seu terminal. | ✅ | ✅ | ❌ | ❌ |
| Usa seus logins do Chrome As contas que você já usa no Chrome estão lá na primeira execução. | ✅ | ❌ | ✅ | ❌ perfil separado |
| Parece um navegador normal Alguns sites, como X e LinkedIn, sinalizam navegadores headless e automatizados. | ✅ | ➖ frequentemente sinalizado | ✅ | ➖ sinalização de automação ativa |
| Sessões compartilham um navegador Várias sessões do Claude Code usam a mesma janela com sessão iniciada ao mesmo tempo. | ✅ | ❌ bloqueio de perfil | ✅ | ❌ bloqueio de perfil |
✅ sim ➖ parcialmente ❌ não. Configurações padrão no macOS, verificadas em outubro de 2026. O Chrome DevTools MCP pode anexar ao seu próprio Chrome com --autoConnect.
Configure em cinco passos
Cerca de dois minutos.
1. Saia do Chrome
Pressione ⌘ Q no Chrome. Fechar a janela não é suficiente.
O agent-chrome copia seu perfil do Chrome. Se o Chrome estiver em execução, a cópia pode perder seus logins.
2. Adicione o plugin
No Claude Code, execute estes dois comandos:
/plugin marketplace add rav4nn/agent-chrome
/plugin install agent-chrome@agent-chrome
O plugin ensina o Claude a configurar e usar o agent-chrome. Ele ainda não dá um navegador ao Claude. O passo 3 faz isso.
Prefere não usar o plugin?
Execute a CLI de configuração com npx. Não é necessário clonar:
npx github:rav4nn/agent-chrome profiles
npx github:rav4nn/agent-chrome add "Work"
Ou clone o repositório:
git clone https://github.com/rav4nn/agent-chrome.git
cd agent-chrome
node bin/agent-chrome.mjs profiles
node bin/agent-chrome.mjs add "Work"
Depois continue com o passo 4.
3. Configure um perfil
Pergunte ao Claude:
Set up agent-chrome for one of my Chrome profiles.
O Claude lista seus perfis do Chrome e pergunta qual você quer. Escolha um, diga Trabalho.
O macOS então informa que agent-chrome-work pode ser executado em segundo plano. Esse é o pequeno proxy para este perfil. Ele usa cerca de 25 MB de memória enquanto espera.
4. Inicie uma nova sessão e teste
Inicie uma nova sessão do Claude Code (ou retome uma) para que as novas ferramentas chrome-work sejam carregadas. Depois pergunte:
Open chrome-work and go to myaccount.google.com. Tell me which Google account is signed in. Don't click or change anything.
Continue digitando enquanto ele executa. A janela do agente tem um tema vermelho e abre atrás do seu terminal.
5. Saia e pergunte novamente
Quando o Claude terminar, saia do Chrome vermelho pelo Dock. Depois pergunte:
Open chrome-work and go to example.com.
A janela volta atrás dos seus aplicativos, ainda com sessão iniciada. Só você a fecha.
Nomeie o perfil em cada prompt
Cada perfil que você adiciona se torna seu próprio servidor MCP, chrome-<name>. Diga o nome e o Claude usa esse perfil, com as contas nas quais ele está conectado. Sem um nome, o Claude pergunta qual você quer dizer.
Open chrome-work and go to reddit.com. Open the first 3 posts and summarise them.
Open chrome-work and check my GitHub notifications. List the ones that need a reply.
Open chrome-personal and find the tracking link for my last Amazon order.
Por que a janela fica atrás
No macOS, o Chrome pula para a frente toda vez que uma ferramenta fala com ele pela porta de depuração (chrome-devtools-mcp#1254). O transporte WebSocket ativa o Chrome.app, e nenhuma configuração de bringToFront: false ajuda. Um pipe (--remote-debugging-pipe) não dispara isso, mas apenas o programa que iniciou o Chrome pode segurar o pipe. Então duas sessões do Claude ou disputam o bloqueio de perfil ou cada uma inicia um Chrome descartável, e você faz login novamente a cada sessão.
O agent-chrome executa um pequeno proxy para cada perfil. O proxy segura o pipe para o Chrome, e cada sessão do Claude se conecta ao proxy. Várias sessões compartilham um Chrome com sessão iniciada, e nenhuma rouba o foco.
Cerca de 500 linhas de Node.js. Uma dependência (ws). Somente localhost. Sem telemetria. MIT.
Como funciona a multiplexação
O proxy inicia o Chrome com --remote-debugging-pipe, o que fornece um canal CDP JSON-over-stdio apenas para o processo que o iniciou. Ele então serve uma interface HTTP e WebSocket localhost no mesmo formato da descoberta --remote-debugging-port do Chrome (/json/version, /json/list, um WebSocket de nível de navegador). chrome-devtools-mcp --browserUrl http://127.0.0.1:9410 se conecta sem saber que não está falando com o Chrome.
Três padrões permitem que muitos clientes MCP compartilhem um pipe:
- Remapeamento de ID de requisição. Cada cliente numera suas requisições
1, 2, 3, ...por conta própria, e esses IDs colidiriam no pipe. O proxy reescreve cadaidrecebido para um ID de proxy único, registraproxyId → {client, originalId, method}, encaminha para o Chrome e restaura o ID original na resposta. - Estado de destino em cache. O proxy ativa a descoberta de destinos e o auto-anexo e armazena em cache cada destino e sessão. Quando um cliente pede descoberta ou auto-anexo, o proxy reproduz o cache para esse cliente em vez de encaminhar a chamada.
- Sessões compartilhadas. Os eventos do Chrome vão para todos os clientes. Os clientes ignoram eventos de sessões que não rastreiam.
[Claude session A] chrome-devtools-mcp ─┐
[Claude session B] chrome-devtools-mcp ─┼── WebSocket(127.0.0.1:9410) ── proxy ── stdio pipe ── [Chrome, profile copy]
[Claude session C] chrome-devtools-mcp ─┘
Bom saber
Por que não rodar o Playwright headless?
Você não consegue ver um navegador headless. Com o agent-chrome, você pode abrir a janela vermelha a qualquer momento, observar o que o Claude faz e corrigir seu prompt ou habilidade quando algo der errado. Se ele parar em um login, um código 2FA ou um CAPTCHA, você clica e conclui essa etapa você mesmo. O Playwright também usa seu próprio perfil, então seus logins do Chrome não estão lá, e você não pode fazer login em uma janela que não consegue ver. O agent-chrome usa uma cópia do seu Chrome real, com sessão iniciada.
Os sites conseguem perceber que o Claude está dirigindo o navegador?
Às vezes. O agent-chrome inicia o Chrome com --disable-blink-features=AutomationControlled, então navigator.webdriver é falso e a verificação mais barata falha. Mas um site ainda pode detectar o depurador anexado e pode observar como a página é usada: cliques sem movimento do mouse, texto que aparece de uma vez, ações mais rápidas que uma pessoa. Seu perfil real, com histórico e cookies, ajuda muito. Isso não torna o Claude invisível.
Posso usar o Chrome stealth em vez disso?
Para esconder automação, builds stealth como o Patchright vão além do agent-chrome. Eles escondem rastros de depurador que o agent-chrome não esconde. Mas eles não resolvem foco ou compartilhamento. A ferramenta que inicia o navegador é dona dele. Por um pipe, apenas aquela sessão do Claude pode dirigi-lo, e uma segunda sessão encontra o bloqueio de perfil. Por uma porta de depuração, várias sessões podem se conectar, mas esse é o caminho que puxa o Chrome para a frente no macOS. O proxy do agent-chrome segura o pipe e permite que todas as sessões o compartilhem. E aponte o stealth para o Chrome real, não para o Chromium: o Chromium não consegue ler os cookies em um perfil do Chrome copiado, então você começaria sem sessão iniciada.
E quanto ao uso de computador?
O uso de computador move seu mouse real e digita com seu teclado, então você não consegue trabalhar enquanto ele executa. Ele lê uma captura de tela a cada etapa, o que o torna lento, e uma tela significa um agente por vez. O agent-chrome trabalha em uma janela atrás da sua, e você mantém seu teclado.
O Claude usa meu perfil real do Chrome?
Não. Ele usa uma cópia. O Chrome recusa depuração remota em sua pasta de dados padrão (DevTools remote debugging requires a non-default data directory.), então o agent-chrome copia o perfil em vez de usá-lo no lugar. Isso é separado da restrição de porta do Chrome 136+. No APFS, a cópia não ocupa espaço extra em disco até que os dois se afastem. Seu próprio Chrome continua sendo seu.
Entrei em um site no meu próprio Chrome. Por que a janela do agente está sem sessão?
A cópia não capta novos logins. Entre na janela vermelha uma vez, ou saia do Chrome e execute add "Work" --recopy para uma cópia nova.
Quanta memória ele usa?
O proxy usa cerca de 25 MB enquanto espera, e nenhuma CPU. Uma janela de agente aberta é um Chrome completo e separado: cerca de 500 MB para uma página simples. Sites pesados e tempo de atividade longo adicionam mais: um com Gmail aberto por um dia mediu 1,6 GB. Saia da janela para liberar.
O que sincroniza de volta para minha conta do Google?
add desativa a sincronização na cópia para temas, URLs digitados, abas, grupos de abas, extensões e aplicativos. A cópia é seu próprio dispositivo de sincronização. Senhas, favoritos, preenchimento automático e configurações ainda sincronizam, então uma senha ou favorito que o agente salvar chega à sua conta real do Google.
Meu gerenciador de senhas funciona na janela do agente?
Não. As extensões estão desativadas lá. Entre manualmente uma vez, ou deixe o próprio gerenciador de senhas do Chrome preencher o formulário.
Duas sessões do Claude podem usar o mesmo perfil?
Sim. Elas compartilham uma janela de agente, e cada sessão pode ver e dirigir cada aba nela. O proxy não impõe propriedade de abas. A habilidade do plugin diz a cada sessão do Claude para trabalhar apenas nas abas que ela abriu, o que mantém as sessões fora do caminho umas das outras, mas é uma convenção, não uma fronteira de segurança. Duas sessões que ativam o Runtime na mesma aba ao mesmo tempo podem competir.
Um site pode se conectar ao proxy?
Não. Quem se conecta controla um navegador com sessão iniciada, então o proxy recusa qualquer requisição com um cabeçalho Origin (navegadores enviam um, então uma página web não consegue se conectar ao 127.0.0.1) e qualquer Host diferente de 127.0.0.1, localhost ou [::1] (DNS rebinding). Outros programas no seu Mac ainda podem se conectar, da mesma forma que com a porta de depuração do próprio Chrome.
Posso usar o Playwright através do proxy?
Não. O connectOverCDP do Playwright não funciona através do proxy. Use o chrome-devtools-mcp, que a configuração registra para você.
Windows ou Linux?
Ainda não. O bug de foco é um problema do macOS, e a CLI de configuração é exclusiva do macOS. O multiplexador de pipe em si funcionaria lá.
Como faço para remover?
Peça ao Claude para remover agent-chrome para chrome-work, ou execute npx github:rav4nn/agent-chrome remove work. Ele para o proxy, remove o item de login e cancela o registro do servidor MCP. Adicione --delete-profile para excluir a cópia também.
Referência
Comandos
| Comando | O que faz |
|---|---|
profiles | Lista seus perfis do Chrome (pasta, nome, e-mail) e o slug de cada um que você configurou |
add <profile> | Configura um perfil. <profile> é a pasta dele ("Profile 5"), nome de exibição ou e-mail |
remove <slug> | Para o proxy, exclui o LaunchAgent e cancela o registro do servidor MCP. Mantém a cópia |
status | Uma linha por slug instalado: porta, proxy ativo, janela do agente aberta, servidor MCP registrado |
update | Atualiza o código do proxy na pasta de execução e reinicia cada proxy |
Opções para add:
| Opção | Padrão | Significado |
|---|---|---|
--name <slug> | o nome do perfil, em minúsculas, com hífens | O servidor MCP é chrome-<slug> |
--port <n> | primeira porta livre a partir de 9410 | Porta do proxy |
--color <#rrggbb> | #D50000 | Cor do tema da janela do agente |
--recopy | desativado | Substitui uma cópia existente por uma nova do seu perfil real |
--force | desativado | Copia enquanto o Chrome está em execução. Bancos de dados ativos podem ser copiados em um estado misto, e a cópia pode perder sessões iniciadas |
--dry-run | desativado | Imprime o plano, não altera nada |
remove aceita --delete-profile para excluir a cópia também, e --dry-run. update aceita --dry-run.
Executar add novamente para o mesmo perfil é seguro. Ele mantém a cópia e a porta existentes, e reescreve o tema, o LaunchAgent e o servidor MCP.
O que add faz
- Copia o perfil para
~/Library/Application Support/agent-chrome/profiles/<slug>/. Ele usa um clone APFS, então a cópia é rápida e não ocupa espaço extra em disco até que os dois divergirem. - Dá à cópia um tema colorido (padrão
#D50000), para você distinguir a janela do agente da sua. - Desativa a sincronização na cópia para temas, URLs digitados, abas, grupos de abas, extensões e aplicativos. Temas sincronizados empurrariam a cor do agente de volta para o seu perfil real, e o histórico do agente cairia nele.
- Instala o proxy em
~/Library/Application Support/agent-chrome/runtime/e um LaunchAgent,io.github.rav4nn.agent-chrome.<slug>, que o inicia no login através de um pequeno lançador,launchers/agent-chrome-<slug>. Os logs vão para~/Library/Logs/agent-chrome/<slug>.log. O Monitor de Atividade lista o proxy comonode. Você pode desativar o item de login em Ajustes do Sistema > Geral > Itens de Login e Extensões, mas então o Claude não consegue abrir esse perfil. - Registra um servidor MCP no escopo do usuário,
chrome-<slug>: chrome-devtools-mcp apontando para a porta do proxy. Ele usa seuchrome-devtools-mcpglobal se você tiver um, enpx chrome-devtools-mcp@latestse não. Sem a CLIclaudeno seu PATH, ele imprime o JSON para colar em~/.claude.json.
Adicione --dry-run para ver cada escrita de arquivo e comando sem executar nenhum deles.
Usando no Claude
- As ferramentas são
mcp__chrome-<slug>__*, do chrome-devtools-mcp. - Abra páginas com
new_pageebackground: true. A primeira nova aba inicia o Chrome. - Cada sessão funciona apenas nas abas que abriu. Isso é uma regra na habilidade do plugin, não algo que o proxy impõe: todas as sessões compartilham uma janela e podem ver e controlar cada aba nela.
- Só você fecha a janela do agente. Depois que você a fecha, as ferramentas relatam nenhuma página. O próximo
new_pagea abre novamente. - Quando a última aba do agente fecha (Sair, o botão de fechar da janela ou a última aba), o proxy sai desse Chrome, então nenhum Chrome vazio permanece no Dock.
- Se um site mostrar que você saiu da sessão, faça login dentro da janela do agente.
A habilidade do plugin informa tudo isso ao Claude.
Executando o proxy manualmente
A CLI cobre a configuração usual. Para executar o proxy você mesmo:
npm install --omit=dev
node pipe-cdp-proxy.mjs --port 9410 \
--user-data-dir "$HOME/Library/Application Support/Chrome-Pipe-Proxy" \
--profile-directory Default
| Flag | Padrão | Descrição |
|---|---|---|
--port | 9410 | Porta em que o proxy escuta para clientes MCP |
--chrome-path | /Applications/Google Chrome.app/Contents/MacOS/Google Chrome | Binário do Chrome |
--user-data-dir | $HOME/Library/Application Support/Chrome-Pipe-Proxy | Pasta de dados do Chrome. Não deve ser o padrão do Chrome |
--profile-directory | Default | Pasta do perfil dentro de --user-data-dir |
Verificação de saúde:
curl -s http://127.0.0.1:9410/proxy/status
Ela retorna chromeRunning, chromePid, clients e contagens de cache. Defina PROXY_DEBUG=1 para registrar cada mensagem CDP.
Testes
npm test # CLI unit tests, and the proxy's local-tools-only guard
node test/live-check.mjs <port> # drives a real Chrome through a running proxy with its window closed
A verificação ao vivo carrega o Puppeteer de uma instalação global do chrome-devtools-mcp.
Mudanças em relação ao upstream
agent-chrome é um fork de mimkorn/chrome-pipe-proxy. O proxy é a mesma ideia. Este fork adiciona uma CLI de configuração, um plugin do Claude Code e estas mudanças no proxy:
--profile-directoryescolhe o perfil do Chrome dentro de--user-data-dir.- O Chrome inicia apenas quando um cliente abre uma aba ou contexto de navegador. Uma conexão, uma chamada de descoberta ou uma lista de páginas enquanto o Chrome está desligado recebe um navegador vazio, não um lançamento.
- Sem reinício automático. Quando você sai do Chrome, o proxy derruba seus clientes, e uma reconexão não traz a janela de volta.
- Novas abas abrem em segundo plano. O proxy abre uma nova janela apenas quando nenhuma existe, e responde ao
Page.bringToFrontele mesmo. Ambos costumavam elevar a janela no macOS, mesmo pelo pipe. - O proxy envia
Runtime.disableantes doRuntime.enablede um cliente em uma aba compartilhada, para que uma sessão posterior possa assumir uma aba que uma anterior deixou aberta. - As mensagens de cada cliente mantêm sua ordem durante a espera de lançamento, e uma mensagem malformada não para mais a fila.
- O Chrome inicia sem extensões, sem janela de inicialização e sem limitação de uma janela que fica atrás de outros aplicativos.
- Apenas ferramentas locais: a proteção
OrigineHostdescrita em Bom saber. O upstream aceitou ambas. - A CLI de configuração, o plugin e a habilidade do Claude Code, e os testes são novos.
Créditos
O proxy vem de mimkorn/chrome-pipe-proxy por Simon Democko. Seu roteamento multi-cliente (remapeamento de ID de requisição, propriedade de sessão) segue henu-wang/chrome-mcp-proxy, que resolve uma forma diferente do mesmo problema com um proxy de filtro WebSocket-para-WebSocket.
Licença
MIT. Veja LICENSE.