Pular para o conteúdo
claudemods

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

Instale dentro do Claude Code:

/plugin install terminal-browser --marketplace zenbu-labs/terminal-browser
Todas as opções de instalação ↓

O 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. 1.Uma linha, dentro do Claude Code

    /plugin install terminal-browser --marketplace zenbu-labs/terminal-browser

    Cole em uma sessão em andamento (v2.1.275+). O Claude Code pede primeiro para adicionar o marketplace.

  2. 2.Pelo seu shell

    claude plugin marketplace add zenbu-labs/terminal-browser
    claude plugin install terminal-browser@terminal-browser

    Depois execute /reload-plugins em qualquer sessão que já esteja aberta.

  3. 3.Experimente sem instalar

    git clone https://github.com/zenbu-labs/terminal-browser
    claude --plugin-dir ./terminal-browser/claude-code-plugin

    Carrega 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 watchBridge faz long-polling em /state e 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.tsx coleta 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/take e 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 programa terminal-browser, com capabilities e claude-bridge launch. São arrays de argv com timeouts de 10 s e 20 s. Em um checkout de desenvolvimento, ele executa node ../cli/dist/main.js no lugar, se esse arquivo existir.
  • Rede ($.http.fetch): apenas http://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 /browser diz "Please install terminal-browser first": instale o programa e confirme que ele está no seu PATH.
  • 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.
Agent Profiler em execução no Claude CodeDestaque

Agent 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

Agent Radar em execução no Claude CodeDestaque

Agent 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

Agent Tree em execução no Claude CodeDestaque

Agent 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

Context Inspector em execução no Claude CodeDestaque

Context 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.