> ## Documentation Index > Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt > Use this file to discover all available pages before exploring further. # Automação de Navegador (@browser) > Controle um Chrome/Chromium local de verdade pelo DevTools Protocol — abra uma página, leia-a como texto com elementos interativos numerados, clique, digite, rode JS, tire screenshot e inspecione console + rede. O loop de verificação para trabalho web. Sem chaves, zero dependência nova. A tool **`@browser`** controla um **Chrome/Chromium local de verdade** para que o agente possa **ver e interagir com páginas web** como uma pessoa faria: abrir uma URL, ler a página renderizada como texto, clicar e digitar em elementos, rodar JavaScript, capturar screenshots e inspecionar a atividade de **console** e **rede** da página. É o **loop de verificação** para trabalho web — o agente constrói ou altera um frontend, então **realmente olha para ele** e o depura a partir do que a página registrou e requisitou, em vez de adivinhar pelo código-fonte. O `@browser` fala o **Chrome DevTools Protocol (CDP)** diretamente sobre o cliente websocket que o ChatCLI já embarca — **zero dependência nova**, sem driver, sem runtime baixado, sem chave de API. Só precisa de um **navegador da família Chromium instalado localmente** (Google Chrome, Chromium, Brave ou Edge). *** ## Como funciona ```text theme={"system"} @browser open http://localhost:3000 │ ▼ inicia um Chrome headless (primeiro uso) — reaproveitado a sessão inteira │ ▼ conecta via CDP (websocket) → navega → aguarda o load │ ▼ snapshot: título, URL, elementos interativos NUMERADOS, texto visível │ ▼ click [n] / type [n] "texto" → snapshot de novo → console / network p/ depurar │ ▼ close (ou morre automaticamente quando o ChatCLI encerra) ``` 1. **Início preguiçoso** — o primeiro `open` inicia um navegador; todo comando seguinte reaproveita essa **sessão única com estado**. 2. **CDP sobre websocket** — navegação, leitura do DOM, screenshots e captura de eventos fluem pelo websocket do DevTools. Sem Selenium/Playwright, sem binário externo. 3. **Snapshot como texto** — a página é renderizada em texto amigável ao modelo, com cada elemento interativo **marcado e numerado** para o agente endereçá-los com precisão. 4. **Captura contínua** — mensagens de console (incluindo erros) e respostas de rede são capturadas em rings limitados, então você pode perguntar "o que a página registrou?" **depois do fato**. 5. **Morre com a sessão** — um navegador headless nunca sobrevive ao ChatCLI; é fechado no encerramento do CLI (ou explicitamente com `close`). *** ## Subcomandos Invoque com um envelope JSON `{cmd, args}` ou a forma argv plana. O modelo chama `@browser` automaticamente em `/agent` e `/coder` quando precisa olhar uma página. | Subcomando | O que faz | Args principais | | :----------- | :------------------------------------------------------------------------------------------- | :----------------------------------------------- | | `open` | Navega para uma URL (inicia o navegador no primeiro uso) e retorna um **snapshot da página** | `url` (obr.) | | `snapshot` | A página atual como texto: título, URL, elementos interativos numerados, texto visível | `--max N` (limita o texto) | | `click` | Clica um elemento pela sua **ref `[n]`** do último snapshot **ou** um seletor CSS | `target` (obr.) | | `type` | Digita em um input; `--submit` pressiona Enter / envia o form | `target` (obr.), `text`, `--submit` | | `scroll` | Move a viewport | `down` · `up` · `top` · `bottom` · `--to target` | | `eval` | Roda uma expressão JavaScript na página e retorna o valor | `javascript` (obr.) | | `screenshot` | Captura a viewport como **PNG** | `--file path` (opcional) | | `console` | As mensagens de console capturadas (incluindo erros) | `--tail N` | | `network` | As respostas de rede capturadas: método, status, URL | `--tail N` | | `back` | Voltar no histórico | — | | `status` | Se há uma sessão de navegador ativa e em que página está | — | | `close` | Fecha a sessão do navegador | — | *** ## Refs vs. seletores CSS Todo `snapshot` marca cada elemento interativo com um atributo `data-chatcli-ref` e retorna uma **listagem numerada**. `click` e `type` aceitam **tanto** esse número de ref `[n]` **quanto** um seletor CSS puro: ```text theme={"system"} Elementos interativos: [1] link "Docs" → /docs [2] input "Busca" (type=search) [3] button "Entrar" @browser click 3 # pela ref (recomendado — sem adivinhar seletores) @browser click #login-btn # por seletor CSS ``` As refs são estáveis **até a próxima navegação**. Depois de `open` numa nova URL ou de um `click` que dispara navegação, tire um `snapshot` novo antes de endereçar elementos por `[n]` de novo. *** ## Um exemplo prático Construa uma página no `/coder`, então verifique-a de ponta a ponta: ```text theme={"system"} # 1) Abra o app que o coder acabou de subir @browser open http://localhost:3000 → Page: My App — Home Elementos interativos: [1] link "Produtos" [2] input "Email" (type=email) [3] button "Assinar" # 2) Preencha o form e envie @browser type 2 "user@example.com" @browser click 3 # 3) Veja o que aconteceu @browser snapshot → Page: My App — Obrigado! "Você está inscrito." # 4) Algo estranho? Depure a partir da própria página @browser console --tail 20 → [error] Uncaught TypeError: cannot read 'id' of undefined (app.js:42) @browser network --tail 10 → 500 POST http://localhost:3000/api/subscribe (Fetch) ``` O agente agora sabe que o botão funcionou na UI mas o backend retornou **500**, e o erro exato do console — o loop completo de verificar-e-corrigir sem sair do ChatCLI. *** ## Variáveis de ambiente | Variável | Descrição | Default | | :------------------------- | :---------------------------------------------------------------- | :-------------------------------------- | | `CHATCLI_BROWSER_BIN` | Caminho do binário do navegador a usar | auto-detecta Chrome/Chromium/Brave/Edge | | `CHATCLI_BROWSER_HEADLESS` | Rodar headless (`true`) ou abrir uma **janela visível** (`false`) | `true` | ```bash theme={"system"} # Assistir o agente controlar uma janela de verdade export CHATCLI_BROWSER_HEADLESS=false # Apontar para um navegador específico export CHATCLI_BROWSER_BIN="/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" ``` *** ## Segurança Comandos de observação são **read-only** e pulam a confirmação — o agente pode olhar à vontade: `open`, `snapshot`, `screenshot`, `console`, `network`, `scroll`, `back`, `status`, `close`. Comandos que **agem** sobre a página — `click`, `type` e `eval` — podem disparar ações reais em sites remotos, então passam pelo **gate de segurança** padrão como qualquer outra tool que muta estado. Veja [Segurança do Modo Coder](/pt/features/coder-security). O `@browser` controla um navegador de verdade logado em qualquer perfil que ele inicie. Prefira a sessão descartável default para páginas não confiáveis, e trate `click`/`type`/`eval` em sites externos como as operações com efeito colateral que são. *** ## Notas * **Uma sessão por processo**, iniciada preguiçosamente no primeiro `open` e reaproveitada em toda chamada. * Console e rede são capturados **continuamente** em rings limitados — `console`/`network` leem o histórico recente, não precisam ser "armados" antes. * `screenshot` grava um PNG (default no diretório temporário, ou `--file path`). Combine com [`@view`](/pt/features/vision-input) para o modelo **olhar o screenshot** que acabou de tirar. * O navegador é **sempre** fechado no encerramento do ChatCLI; um Chrome headless perdido nunca sobrevive à sessão. ## Próximos passos Anexe um screenshot que o `@browser` capturou para o modelo ver com os próprios olhos. Ler, escrever, aplicar patch e executar — combine com `@browser` para construir e então verificar. O catálogo completo de tools builtin e como o agente as usa. `@webfetch`, `@websearch` e o cliente HTTP endurecido compartilhado.