terminal-browser: um navegador no Claude Code para páginas web ao vivo
Abre um navegador web real em um painel dentro do Claude Code com /browser, desenhado com o protocolo gráfico do kitty.
Permissões
- Lê arquivosPode ler arquivos e listar diretórios na sua máquina ($.fs.read / list / stat / exists).
- Executa comandosPode executar programas de shell na sua máquina ($.process.run / spawn). Confira no código-fonte exatamente quais.
- RedePode fazer requisições HTTP ou se comunicar com servidores MCP ($.http.fetch / $.mcp.*).
- Intercepta chamadas de ferramentasVê cada chamada de ferramenta que o Claude faz (tool.call / tool.check) e pode bloqueá-la ou alterá-la.
- Altera a interfaceDesenha na interface do Claude Code: faixas, painéis, texto de status, notificações (ui.render / $.ui.*).
- Adiciona comandos/ferramentasRegistra novos comandos de barra ou ferramentas que você ou o Claude podem acionar ($.command.register / $.tool.register).
- testado com
- v2.1.310
- último teste
- requer
- Claude Code ≥ 2.1.287
- superfícies
- painel
- código-fonte
- Zenbu Labs (zenbu-labs) (MIT)
Instale dentro do Claude Code:
/plugin install terminal-browser --marketplace zenbu-labs/terminal-browserO que este mod faz?
O terminal-browser, da Zenbu Labs, é um mod de navegador no Claude Code: ele executa um navegador web real dentro do Claude Code. Digite /browser e um painel se abre ao lado da conversa mostrando uma página ao vivo. Digite /browser example.com e esse site é carregado. Execute /browser de novo, ou /browser close, para fechá-lo. Você pode clicar, digitar e rolar no painel, e a entrada vai para a página.
Um navegador baseado em Chromium, parte do programa separado terminal-browser, faz a renderização de fato. O plugin o inicia, envia a ele o tamanho do painel e a sua entrada de mouse e teclado, e desenha os quadros dele como imagens no painel. Por isso ele só funciona em terminais que suportam o protocolo gráfico do kitty, como Ghostty e kitty.
O plugin é útil quando você constrói um app web com o Claude. Você pode conferir o servidor de desenvolvimento em localhost:3000 ou ler um relatório em HTML sem sair da sessão. O autor marca o plugin como experimental porque ele depende da API de function hooks, que ainda está mudando.
Instalação
Use o bloco de instalação, que adiciona o marketplace do autor e instala o plugin a partir dele. Você também precisa do programa terminal-browser no seu PATH (veja as perguntas frequentes). Execute /reload-plugins em qualquer sessão que já estivesse aberta.
$ install terminal-browser
Requer Claude Code ≥ 2.1.287
Instala a partir do marketplace do autor: zenbu-labs/terminal-browser
1.Uma linha, dentro do Claude Code
/plugin install terminal-browser --marketplace zenbu-labs/terminal-browserCole em uma sessão em andamento (v2.1.275+). O Claude Code pede primeiro para adicionar o marketplace.
2.Pelo seu shell
claude plugin marketplace add zenbu-labs/terminal-browser claude plugin install terminal-browser@terminal-browserDepois execute /reload-plugins em qualquer sessão que já esteja aberta.
3.Experimente sem instalar
git clone https://github.com/zenbu-labs/terminal-browser claude --plugin-dir ./terminal-browser/claude-code-pluginCarrega o mod só para uma sessão. Nada é adicionado às suas configurações.
Como funciona
O plugin registra um comando /browser quando uma sessão começa no terminal. O handler do comando é curto. Ele vem de hooks/register.tsx:
on('command.run', { command: 'browser' }, async ($, e) => {
const arg = e.args.trim()
if (arg === 'close' || (!arg && state.open)) {
await closeBrowser($)
return { text: 'Closed terminal-browser' }
}
const opened = await openBrowser($, arg || null)
return { text: opened.ok ? 'Opened terminal-browser' : opened.error }
})Na primeira vez que o navegador abre, o startBridge executa terminal-browser capabilities para verificar se a versão instalada suporta embedding e image-frames. Em seguida ele executa terminal-browser claude-bridge launch, que imprime uma porta local e um token aleatório. Depois disso, tudo passa por HTTP para 127.0.0.1 nessa porta, com o token como cabeçalho bearer:
- O
watchBridgefaz long-polling em/statee copia cada novo quadro para o painel com$.ui.blit. O quadro vem de memória compartilhada, então nenhum dado de imagem passa pela resposta HTTP. - O
surface.tsxcoleta as teclas e os eventos de mouse, a cada 20 ms aproximadamente, e o plugin os envia por POST para/input. Os eventos da roda de rolagem seguem o mesmo caminho. - As mudanças de tamanho do painel são enviadas por POST para
/size, e a primeira URL para/open. - Quando o navegador tem texto para o agente, o plugin o retira de
/inbox/takee o coloca na caixa de prompt com$.prompt.fill. Se o navegador anexou uma captura de tela, a linha dela também é adicionada. Nada é enviado até você pressionar Enter.
Nomes de host simples viram URLs https:// e endereços localhost viram http://. O auxiliar está em hooks/urls.ts.
Personalize
O plugin tem uma única opção, agentTool, que vem desligada por padrão. Quando ligada, o plugin registra duas ferramentas, open e close. O Claude pode chamá-las para mostrar uma página no painel. Defina-a em /config ou em pluginConfigs no ~/.claude/settings.json, como o README mostra.
Outros plugins também podem controlar o navegador. O plugin adiciona $.browser.open({ url }) e $.browser.close() ao engine e inclui os tipos em hooks/browser.d.ts. Com isso, um mod pode adicionar comandos como /tldraw ou /open-pr que abrem uma página no painel.
Permissões e segurança
Lemos todos os arquivos de claude-code-plugin/ no commit 2165ae7. São eles register.tsx, surface.tsx, bridge-protocol.ts, urls.ts e o arquivo de tipos. O código é TypeScript simples, sem código minificado ou empacotado.
- Executa comandos (
$.process.run): apenas o programaterminal-browser, comcapabilitieseclaude-bridge launch. São arrays de argv com timeouts de 10 s e 20 s. Em um checkout de desenvolvimento, ele executanode ../cli/dist/main.jsno lugar, se esse arquivo existir. - Rede (
$.http.fetch): apenashttp://127.0.0.1:<port>, a bridge local iniciada acima, com um token por execução. O README observa que o seu sistema operacional pode perguntar se o terminal pode acessar a rede local. - Preenche o prompt (
$.prompt.fill): o texto que o navegador envia para o agente é colocado na caixa de entrada. Ele nunca é enviado por conta própria. - Adiciona ferramentas (
$.tool.register): somente quando você ativa o agentTool. - Ele não grava arquivos, não altera configurações e não lê a sua transcrição.
O navegador em si é o programa separado terminal-browser. Ele é instalado com um script curl | bash e não faz parte deste plugin. No mesmo repositório, esse programa tem código que envia eventos de uso anônimos (inicialização, usuário ativo diário, atualização, tipo de falha) para o endpoint da PostHog na UE. O código os ignora quando DO_NOT_TRACK ou TERMINAL_BROWSER_NO_TELEMETRY está definido. O navegador também carrega os sites que você abre, como qualquer navegador.
- Lê arquivos
- Pode ler arquivos e listar diretórios na sua máquina ($.fs.read / list / stat / exists).
- Executa comandos
- Pode executar programas de shell na sua máquina ($.process.run / spawn). Confira no código-fonte exatamente quais.
- Rede
- Pode fazer requisições HTTP ou se comunicar com servidores MCP ($.http.fetch / $.mcp.*).
- Intercepta chamadas de ferramentas
- Vê cada chamada de ferramenta que o Claude faz (tool.call / tool.check) e pode bloqueá-la ou alterá-la.
- Altera a interface
- Desenha na interface do Claude Code: faixas, painéis, texto de status, notificações (ui.render / $.ui.*).
- Adiciona comandos/ferramentas
- Registra novos comandos de barra ou ferramentas que você ou o Claude podem acionar ($.command.register / $.tool.register).
Compatibilidade e solução de problemas
Validamos o plugin com claude plugin validate no Claude Code 2.1.310 no commit 2165ae7. A validação passou com um aviso de diretório do plugin. O plugin não tem testes, então o claude plugin test não foi executado. O repositório upstream avançou desde esse commit, mas nenhum dos commits posteriores mexe em claude-code-plugin/, então o código revisado continua sendo o plugin atual. Esta é uma página de nível padrão: sem gravação de demonstração. Os function hooks são obrigatórios, então você precisa do Claude Code 2.1.287 ou mais recente.
- O
/browserdiz "Please install terminal-browser first": instale o programa e confirme que ele está no seuPATH. - Ele diz que uma versão mais nova é necessária: execute
terminal-browser upgrade. - A tela fica embaralhada ou o painel continua vazio: provavelmente o seu terminal não tem kitty graphics com unicode placeholders, ou você está dentro do tmux ou de outro multiplexador.
- O mouse está um pouco fora de posição: o README lista isso como uma limitação conhecida, porque o Claude Code não informa posições de mouse em pixels.
- O painel não fica mais largo: o Claude Code mantém uma largura mínima para a área do chat.
Perguntas frequentes
- Preciso de algo além do plugin para usar este navegador no Claude Code?
- Sim. O plugin só desenha o painel; o navegador em si é o programa terminal-browser, que você instala separadamente (curl -fsSL https://terminal-browser.sh/install | bash, ou brew install terminal-browser). Sem ele, o /browser responde "Please install terminal-browser first". Se a versão instalada for antiga demais, ele pede que você execute terminal-browser upgrade.
- Em quais terminais ele funciona?
- Apenas em terminais que suportam o protocolo gráfico do kitty com unicode placeholders, como Ghostty, kitty e terminais baseados na libghostty, como cmux e supacode. Em outros terminais, o README avisa que abrir o navegador pode embaralhar a tela. Multiplexadores como o tmux costumam quebrá-lo por enquanto.
- O Claude pode abrir páginas no navegador por conta própria?
- Somente se você ativar a opção agentTool, que vem desligada por padrão. Ela adiciona as ferramentas open e close que o modelo pode chamar. Sem ela, o Claude ainda pode usar a CLI terminal-browser para abrir o navegador em um painel dividido, como o README observa.
- Como fecho o painel do navegador?
- Execute /browser close, ou /browser sem argumento enquanto o painel estiver aberto. Fechar o painel no Claude Code também avisa o terminal-browser de que o navegador foi fechado.
- Outros mods podem abrir o navegador?
- Sim. O plugin adiciona $.browser.open({ url }) e $.browser.close() para os hooks de outros plugins. O README mostra um comando /tldraw criado dessa forma.
# Mods relacionados
DestaqueAgent Profiler
Para onde vai o tempo de uma sessão do Claude Code: modelo, ferramentas, subagentes, ao vivo. Com exportação OTLP.
- status
- painel
- notificação
- Grava arquivos
- Rede
- Intercepta chamadas de ferramentas
- Altera a interface
- Adiciona comandos/ferramentas
testado com v2.1.303
DestaqueAgent Radar
Uma linha ao vivo acima do prompt por subagente em execução: tempo, ferramentas e ação atual, mais um painel /radar.
- acima do prompt
- painel
- notificação
- Intercepta chamadas de ferramentas
- Lê seus prompts
- Altera a interface
- Adiciona comandos/ferramentas
testado com v2.1.291
DestaqueAgent Tree
Um painel lateral que desenha os subagentes como caixas, com a sessão principal, o consultor e um registro da sessão.
- painel
- status
- Intercepta chamadas de ferramentas
- Lê seus prompts
- Altera a interface
- Adiciona comandos/ferramentas
testado com v2.1.310
DestaqueContext Inspector
Mostra o que preenche o contexto do Claude Code, quanto é desperdício e o que a compactação manteve.
- status
- painel
- notificação
- Grava arquivos
- Intercepta chamadas de ferramentas
- Lê seus prompts
- Altera a interface
- Adiciona comandos/ferramentas
testado com v2.1.303
Mais em Painéis e dashboards, Ferramentas que você adiciona ao Claude.