Ascended Browser

ascended-browser

Um navegador real para seu agente de IA. Um comando para adicionar.

Um navegador real para agentes de IA, como um servidor MCP. Seu agente abre páginas, lê elas e age sobre elas por meio de ações verificadas: ele preenche um formulário inteiro em uma única chamada, escolhe "Sra." em um menu suspenso React personalizado pelo nome e é informado sobre o que a página fez em resposta, em vez de clicar em coordenadas e torcer para funcionar.

É o navegador da Ascended, empacotado separadamente: Camoufox (um Firefox endurecido que parece um navegador de pessoa para os sites que visita) por trás do mesmo despachante de ferramentas, leitura de página e formatação de resultados que o próprio agente da Ascended usa.

Veja funcionando

Três execuções reais do Claude Code com apenas este servidor anexado, em sites ao vivo. O painel lateral é a transcrição do próprio Claude Code: cada chamada de ferramenta que ele fez e o que retornou, incluindo erros, com o tempo real decorrido. A espera é cortada e o tempo da ferramenta é acelerado; o ponteiro, os quadros do dispositivo, os painéis do devtools e os contornos são desenhados depois a partir do log de eventos do servidor (demo/record_demo.py), então eles se posicionam sobre o que o agente realmente tocou e leu. As gravações de tela completas e sem edição estão em videos/unedited/ (o navegador é controlado via Playwright, então nenhum ponteiro do SO aparece nelas).

QA de front-end. react.dev em um celular e um tablet, claro/escuro, capturas de tela antes/depois, uma auditoria destacando os elementos reais problemáticos, console e rede.

Navegação. Digita na busca da Wikipédia, encontra um fato no artigo, depois pesquisa no YouTube e reproduz o primeiro vídeo.

Formulários reais. booking.com: popup, autocompletar de destino, seletor de data, busca, ordenar por preço.

Logins salvos. Você salva um login uma vez; o agente entra com ele e nunca o vê. Construído a partir de uma execução real (demo/login_demo.py, depois demo/login_explainer.py): a saída da CLI, a tela e o texto e as imagens exatos que o agente recebeu.

Clique em qualquer clipe para o MP4 em qualidade total.

Instalação

A partir do Python (3.11 ou mais recente) ou do npm; ambos executam o mesmo servidor.

uvx ascended-browser doctor          # checks the machine; downloads nothing
uvx ascended-browser fetch           # downloads the browser now (~700 MB; otherwise on first use)

npx -y ascended-browser doctor       # the same, from npm

O navegador é o Camoufox 135.0.1-beta.24, a versão em que todos os testes aqui rodaram; ele é fixado, então uma versão mais nova do Camoufox nunca muda o que seu agente controla, e qualquer outro Camoufox que você tenha instalado é deixado como está. Execute fetch uma vez antes de adicionar o servidor a um agente, para que a primeira chamada de ferramenta não espere pelo download.

O pacote npm é um pequeno lançador: ele executa o pacote Python com uvx quando o uv está instalado (o uv traz seu próprio Python), senão com pipx, senão com um venv privado criado com seu Python 3.11+. Use qualquer comando que preferir nas configurações abaixo (npx -y ascended-browser no lugar de uvx ascended-browser).

Linux: instale xvfb para manter o navegador em um display virtual (o mais próximo de uma tela real); sem ele, o navegador roda em modo headless. Em um display, browser_viewport redimensiona a janela real, então as verificações de celular e tablet reorganizam a página nos breakpoints verdadeiros.

Adicione ao seu agente

Claude Code

claude mcp add ascended-browser -- uvx ascended-browser
# or: claude mcp add ascended-browser -- npx -y ascended-browser

Codex

codex mcp add ascended-browser -- uvx ascended-browser

Se o Codex pergunta antes de cada ação do navegador depende do modo de permissão que você escolher no Codex: em Acesso total, ele apenas as executa; em Pedir aprovação, ele pergunta primeiro. Em um modo de sandbox, codex exec não pode perguntar e falha em todas as chamadas: use Acesso total, ou pré-aprove as ferramentas deste servidor adicionando default_tools_approval_mode = "approve" em [mcp_servers.ascended-browser] em ~/.codex/config.toml.

opencode (opencode.json)

{
  "mcp": {
    "ascended-browser": { "type": "local", "command": ["uvx", "ascended-browser"], "enabled": true }
  }
}

Cursor, Windsurf, Claude Desktop e outros clientes: um servidor stdio com comando uvx e argumentos ["ascended-browser"], ou comando npx e argumentos ["-y", "ascended-browser"].

Ferramentas

Ferramenta	O que faz
browser_open	Abre uma URL (ou várias de uma vez) e retorna o que está na página, cada controle com uma ref
browser_observe	Olha a página novamente, ou restringe a uma região, uma consulta ou um filtro
browser_act	navigate, click, fill, fill_form, select, check, date, press, upload, scroll, wait, sequence: cada uma verificada, cada uma respondida com o que mudou
browser_extract	Lê o texto da página e o estado dos campos, find uma frase, lista cada correspondência de um seletor CSS com seu texto e atributos (cada link de produto, cada preço), ou read=console, read=network, read=inspect, read=audit, read=design para depurar uma página
browser_screenshot	Uma imagem, quando uma observação não consegue descrevê-la: canvas, gráficos, layout visual; compare_with compara com uma imagem anterior ou outra aba
browser_viewport	Redimensiona para celular/tablet/desktop (Linux), emula modo escuro, movimento reduzido, cores forçadas ou offline
browser_evaluate	JavaScript somente leitura, verificado por políticas
browser_tabs	Lista, fecha ou suspende abas
browser_flow	Grava uma tarefa uma vez, reproduz na próxima página com novos valores
browser_login	Entra com um login que você salvou (veja Logins salvos); o agente nunca vê seus valores
wait_for_bot_wall	Aguarda uma página de "verificando seu navegador"; pressiona uma caixa de seleção Turnstile/reCAPTCHA se uma bloquear um formulário

Resultados longos voltam cortados, com um evidence_ref que browser_extract pagina, para que uma página enorme não inunde o contexto do agente.

Cada ação espera a página estabilizar, sob um tempo limite rígido, e diz quando seu efeito não pôde ser confirmado. Se um turno terminar enquanto uma ainda estiver em execução, o próximo turno é informado em vez de encontrar uma página que não consegue explicar: um clique interrompido (você parou o turno) é nomeado no próximo resultado para aquela aba, e uma ação cujo servidor morreu (claude -p terminando, uma sessão SSH caindo) é listada com o primeiro resultado da próxima sessão, para que o agente verifique antes de repetir um pedido ou um formulário.

Logins salvos

Salve um login uma vez e o agente pode entrar com ele, sem nunca vê-lo.

uvx ascended-browser login add github.com --username you@example.com   # prompts for the password
uvx ascended-browser login add accounts.example.com --name Work --totp  # also a TOTP secret (or otpauth:// URI)
uvx ascended-browser login list                                         # names, usernames, sites; never passwords
uvx ascended-browser login edit Work --password                         # change only what you pass
uvx ascended-browser login remove Work

O site é o host da página de login (accounts.example.com, não example.com, quando diferem); passe vários para uma conta em vários hosts. Senhas e segredos TOTP vêm de um prompt oculto, ou do stdin com --password-stdin, nunca da linha de comando, onde acabariam no histórico do shell e na lista de processos.

Depois peça ao seu agente para entrar. browser_open informa que existe um login salvo para a página, e browser_login encontra os campos de nome de usuário, senha e código de uso único e digita os valores (submit: true também pressiona o botão). O que o agente recebe:

• Cada resultado de ferramenta é limpo de cada nome de usuário, senha e segredo TOTP salvos, também codificados em URL, escapados em JSON ou HTML: browser_observe, browser_evaluate (ler input.value retorna [redacted]), browser_extract (texto da página, valores de campos, corpos de rede) e resultados de ações. Uma página que imprime "Conectado como voce@exemplo.com" é lida como "Conectado como [oculto]".
• Cada captura de tela é mascarada antes de chegar ao agente: campos de senha, cartão e código de uso único, campos de nome de usuário e email, e qualquer valor salvo exibido como texto da página.

Para sites que um login salvo não consegue preencher (single sign-on, passkeys, um CAPTCHA, um código enviado por email), entre manualmente uma vez:

uvx ascended-browser signin https://example.com/login   # opens the browser; sign in, then press Enter

Os cookies permanecem no perfil do navegador que toda sessão de agente posterior inicia. Feche as sessões de agente em execução primeiro, para que o login caia no perfil salvo em vez de uma cópia da sessão.

O cofre é logins.db no diretório de dados, legível apenas pelo seu usuário, e não criptografado (como arquivos de credenciais gh ou aws). A limpeza e o mascaramento cobrem o que as ferramentas do navegador retornam. Um agente que também tenha ferramentas de shell ou arquivos (Claude Code, Codex) roda como você e pode ler qualquer arquivo que você puder, incluindo este. Negue a ele o caminho das ferramentas de arquivo (no Claude Code, "deny": ["Read(~/.local/share/ascended/**)"] em permissions em ~/.claude/settings.json) e mantenha comandos de shell sob aprovação; um agente livre para executar qualquer comando ainda pode alcançar o arquivo. Valores com menos de 4 caracteres não são limpos, e um valor que a página altera (os últimos quatro dígitos de um cartão, por exemplo) não é correspondido.

Configurações

Variável	Padrão
ASCENDED_BROWSER_WINDOW	oculto	show abre uma janela visível
ASCENDED_DATA_DIR	~/.local/share/ascended/browser	Perfil do navegador (logins persistem), logins salvos (logins.db), arquivos de sessão
ASCENDED_RESULT_MAX_CHARS	24000	Resultados mais longos são cortados com um evidence_ref
ASCENDED_SETTING_<KEY>		Qualquer configuração do navegador, ex. ASCENDED_SETTING_BROWSER_WORKSPACE_OBSERVE_FORMAT=outline
ASCENDED_LOG_LEVEL	WARNING	Logs vão para o stderr

Limitações

• Redimensionamento de janela (browser_viewport predefinições de celular/tablet/desktop ou qualquer largura e altura) funciona no Linux: no display virtual do próprio pacote por padrão, ou no seu display X11 com ASCENDED_BROWSER_WINDOW=show. No macOS e no Windows, a janela mantém o tamanho de inicialização; a emulação (modo escuro, movimento reduzido, cores forçadas, offline) funciona em todos os lugares. Grades de capturas de tela em vários tamanhos em uma única chamada não estão incluídas.
• Extração com formato de esquema (um modelo lê a página no seu formato JSON) é um recurso do aplicativo Ascended que precisa de um modelo, então não está neste pacote e seus parâmetros não são expostos. Tudo listado em Ferramentas roda sem um modelo.
• Um processo de servidor é uma sessão de navegador: abas e refs duram até seu cliente desconectar; o perfil (cookies, logins) dura entre sessões. Várias sessões podem rodar ao mesmo tempo: a primeira usa o perfil salvo, e qualquer outra iniciada enquanto ela roda recebe sua própria cópia, já conectada ao que o perfil salvo estava. Logins feitos em uma cópia terminam com essa sessão.

Como é construído

src/ascended_browser/_app é gerado a partir da Ascended por scripts/sync_from_ascended.py: os módulos do navegador copiados como estão, o despachante de ferramentas do navegador e o formatador de resultados extraídos por alcançabilidade, e cada importação do resto do aplicativo reescrita para runtime/ (substitutos autônomos pequenos). A sincronização recusa qualquer importação do aplicativo que não consiga mapear.

Testado com os próprios harnesses de estresse da Ascended executados contra este pacote (tests/stress/), um teste de fumaça MCP no lado do cliente (tests/smoke_mcp.py), e tarefas de sites ao vivo dadas a agentes reais (tests/agents/). Logins salvos têm os seus próprios: tests/test_logins.py (a CLI do cofre e o limpador), tests/login_redaction_mcp.py (um cliente real entra em uma página que ecoa o login em seu texto, DOM e rede, e nenhuma ferramenta pode mostrá-lo; com o tesseract instalado, ele também lê as capturas de tela) e tests/signin_persists.py.

O que foi verificado até agora: Linux (Python 3.11, 3.12 e 3.14), com Claude Code e Codex (0.160) em tarefas de sites ao vivo, opencode em uma tarefa de navegação, e o lançador npm via uvx e via seu próprio venv. macOS e Windows devem funcionar em headless ou com uma janela visível, mas não foram testados.

Licença

MIT. O axe-core incluído (_app/browser_vendor/axe-core) é MPL-2.0 e mantém seu aviso no arquivo.