macOS arm64/x86_64 e Linux x86_64/arm64. Binário único, sem dependências de runtime.

Downloads diretos: [macOS arm64](https://kuri.trilok.ai/download/v0.6.0/kuri-v0.6.0-aarch64-macos.tar.gz) · [macOS x86_64](https://kuri.trilok.ai/download/v0.6.0/kuri-v0.6.0-x86_64-macos.tar.gz) · [Linux x86_64](https://kuri.trilok.ai/download/v0.6.0/kuri-v0.6.0-x86_64-linux.tar.gz) · [Linux arm64](https://kuri.trilok.ai/download/v0.6.0/kuri-v0.6.0-aarch64-linux.tar.gz)

---

**Automação de navegador e web crawling para agentes de IA. Escrito em Zig. Zero Node.js.**

Automação CDP · Snapshots A11y · Gravação de HAR · Fetcher autônomo · Navegador de terminal interativo · CLI agêntica · Testes de segurança · Controle de dispositivos iOS + Android

[Início Rápido](#-quick-start) · [Benchmarks](#-benchmarks) · [kuri-agent](#-kuri-agent) · [Testes de Segurança](#-security-testing) · [API](#-http-api) · [Habilidades](#-skills) · [Changelog](https://github.com/justrach/kuri/blob/HEAD/CHANGELOG.md)

> **Por que as equipes migram para o Kuri:** builds `ReleaseFast` atuais para Apple Silicon permanecem abaixo de 2 MB por binário, e uma nova execução no Google Flights em 2026-04-23 mediu **3,392 tokens** para um loop completo de `kuri-agent` (`go→snap→click→snap→eval`). Deltas entre ferramentas devem ser executados novamente no mesmo ambiente antes de citar uma porcentagem.

---

## Por que o Kuri vence para agentes

A maioria das ferramentas de navegador foi construída para engenheiros de QA. O Kuri é construído para loops de agentes: leia a página, mantenha o custo de tokens baixo, aja com base em refs estáveis e siga em frente.

- **135 endpoints HTTP** — paridade total com agent-browser e browser-use, da inspeção React ao Core Web Vitals.
- **7 a 12% menos tokens** do que agent-browser em páginas reais, graças ao formato de ref `@eN` e à renderização sem prefixo.
- **Observações 44x mais leves** com `/page/state` (48 tokens) vs snapshot completo (2,124 tokens) para a mesma página do Google Flights.
- **Execução em lote** — `POST /batch` envia N comandos em uma única chamada HTTP, eliminando N-1 round-trips e N-1 turnos de LLM.
- **Compatível com React** — eventos de mouse CDP confiáveis e eventos de teclado por caractere disparam `onClick` e `onChange` do React 18/19.

### Tokens de snapshot: Google Flights `SIN → TPE`

Nova execução em 2026-05-24 neste workspace, medida com `wc -c` e aproximação `chars/4`.

| Ferramenta / Modo | Chars | ~Tokens | Nota |
|---|---:|---:|---|
| `kuri snap` (completo) | 8,499 | **2,124** | Todos os nós + refs interativos |
| `kuri snap` (somente interativos) | ~3,000 | **~750** | Melhor para loops de agente |
| `kuri /page/state` | 190 | **48** | Observação leve (url, título, scroll%, contagens) |
| agent-browser snap (estimado) | ~9,183 | **~2,295** | Sobrecarga de formato `[ref=e0]` |

### Eficiência de tokens: kuri vs agent-browser

| Página | tokens kuri | tokens agent-browser | Economia |
|---|---:|---:|---|
| example.com | 40 | 35 | -13% (página trivial, agent-browser pula a raiz) |
| Hacker News | 386 | ~440 | **12% menos** |
| Google Flights SIN→TPE | 2,124 | ~2,295 | **7% menos** |

A economia vem do formato compacto do kuri:
- Refs `@e0` (3 caracteres) vs `[ref=e0]` (9 caracteres)
- Sem prefixo `- ` por linha (economiza 2 caracteres × número de linhas)
- Mesma indentação, mesma filtragem de nós

### Custo do fluxo completo: `go → snap → click → snap → eval`

| Ferramenta | Tokens por ciclo |
|---|---:|
| **kuri-agent** | **~3,400** |
| Com `/page/state` em vez do segundo snap | **~1,700** |
| Com `POST /batch` (tudo em uma chamada) | **~1,700** (mesmos tokens, 1 chamada HTTP em vez de 5) |

### kuri vs libretto

[libretto](https://github.com/saffron-health/libretto) (Playwright + Node) é o concorrente mais próximo em custo de tokens por etapa. Medido frente a frente em 2026-07-04 — mesmo Chrome, mesma aba, contagens reais de `tiktoken` `o200k_base` (metodologia completa e reprodução: **[benchmarks/libretto_comparison.md](https://github.com/justrach/kuri/blob/HEAD/benchmarks/libretto_comparison.md)**). A divisão honesta:

| Eixo | Vencedor | Detalhe |
|---|---|---|
| Latência por chamada | **kuri** | 4–117 ms vs 1,344–1,500 ms (**13–376× mais rápido** — servidor persistente vs Node por comando) |
| Tokens de snapshot, página típica | **kuri** | simples 61 vs 151 (2.5×), artigo 265 vs 363 (1.37×) — gramática mais enxuta |
| Tokens de snapshot, lista grande | dividido | padrão do kuri 4,424 vs 813 — o kuri emite todos os 259 refs, o libretto trunca por padrão. Com `limit=5`, o kuri renderiza 555 tokens (**1.46× abaixo do libretto**), 34 refs + marcadores `… +45 more` |
| Trajetória (feed, 9 cliques) | **kuri**, por pouco | 898 vs 939 tokens (base `limit=5` + loop de diff vs loop de exec) — paridade a leve vantagem; a perda de 5.1× da manhã foi devida à base não truncada |
| Execuções repetidas | **libretto** | compila trajetórias em um script Playwright → repetições de 0 tokens; o kuri volta a pagar o loop a cada execução |

**O que o kuri ganhou ao estudar o libretto** (tudo incluído nesta versão): um loop diff-first (`take_snapshot_diff`, ~38 tokens/etapa); um diff adaptativo que recorre a um snapshot completo com um cabeçalho `! page replaced` na navegação; linhas de remoção apenas com a identidade; capturas de tela gravadas em disco (o caminho é retornado, os bytes nunca entram no contexto); `get_page_state` via MCP; e — após reescrever `parseA11yNodes` como um verdadeiro caminhamento de árvore DFS — **truncamento de lista opt-in** (`/snapshot?limit=N`, uma linha `… +K more` por execução limitada), **recaptura com escopo** (`scope=@ref`) e **indentação hierárquica**, também expostos como `uid`/`limit` no `take_snapshot` do MCP. A trajetória de feed de 9 cliques que custava 44,285 tokens com re-snapshots completos ingênuos custa **898** com base truncada + diffs — 49× mais barata, ficando abaixo dos 939 do libretto.

> As tabelas mais antigas acima usam uma aproximação de tokens `chars/4`; a comparação com libretto usa contagens reais de `tiktoken`. Rode novamente os números entre ferramentas no seu próprio ambiente antes de citar uma porcentagem.

### Tamanho do binário e memória

Medido em Apple M4 Pro, macOS 26.4.1. Os binários atuais foram compilados com `-Doptimize=ReleaseFast`.

| Binário | Tamanho atual |
|---|---:|
| `kuri` | 1,093,840 B (1.04 MiB) |
| `kuri-agent` | 629,904 B (615 KiB) |
| `kuri-browse` | 1,089,120 B (1.04 MiB) |
| `kuri-fetch` | 2,063,488 B (1.97 MiB) |

### O RSS permaneceu estável durante a migração para o Zig 0.16

Medido em relação ao build `v0.4.3` `ReleaseFast` atual com `/usr/bin/time -l`.

| Comando | RSS máximo médio `v0.4.3` |
|---|---:|
| `kuri-fetch --version` | ~2.45 MiB |
| `kuri-browse --version` | ~2.45 MiB |
| `kuri-fetch --quiet --dump markdown http://example.com/` | ~9.17 MiB |

## O Problema

Toda ferramenta de automação de navegador arrasta consigo Playwright (~300 MB), um runtime Node.js e uma cascata de dependências npm. Seu agente de IA só quer ler uma página, clicar em um botão e seguir em frente.
**Kuri é um único binário Zig.** Quatro modos, zero runtime:```
kuri           →  CDP server (Chrome automation, a11y snapshots, HAR)
kuri-fetch     →  standalone fetcher (no Chrome, QuickJS for JS, ~2 MB)
kuri-browse    →  interactive terminal browser (navigate, follow links, search)
kuri-agent     →  agentic CLI (scriptable Chrome automation + security testing)

Detecta sua plataforma, baixa o binário correto e instala em `~/.local/bin`.
Os downloads vêm do branch `release-channel` autogerenciado do Kuri. Os binários do macOS são assinados localmente com um certificado Developer ID. Os assets do GitHub Release espelham esses mesmos tarballs.

### bun / npm```sh
bun install -g kuri-agent
# or: npm install -g kuri-agent

The manifest includes exact asset URLs plus SHA-256 checksums for `aarch64-linux`, `x86_64-linux`, `aarch64-macos`, and `x86_64-macos`.

### Platform support

| Platform | Status |
|---|---|
| macOS (`aarch64`, `x86_64`) | Binários pré-compilados, assinados + notarizados |
| Linux (`aarch64`, `x86_64`) | Binários pré-compilados |
| Windows (`x86_64`) | **Experimental — apenas compilação cruzada.** `zig build -Dtarget=x86_64-windows-gnu` é verificado pelo CI, mas automação do Chrome, daemonização, desligamento baseado em sinais, gravação de HAR e o armazenamento de autenticação baseado em arquivo são todos stubs com `error.UnsupportedOnWindows` em tempo de execução. Use **WSL2** se você precisar do conjunto de recursos real. Rastreado em [#153](https://github.com/justrach/kuri/issues/153). |

Kuri depende de primitivas POSIX (`fork`, `clock_gettime`, sockets brutos) em vários pontos, portanto uma porta nativa completa para Windows é um trabalho considerável. A base em nível de compilação acima permite que os caminhos `--version`/`--help` e operações puramente em memória sejam executados; as partes complicadas (Chrome, sockets, daemonize) precisam de implementações Win32 reais antes de saírem da lista de stubs. Se você quiser assumir alguma delas, +1 [#153](https://github.com/justrach/kuri/issues/153) ou abra um PR.

### Compilar a partir do código-fonte

Requer [Zig ≥ 0.16.0](https://ziglang.org/download/).```bash
git clone https://github.com/justrach/kuri.git
cd kuri
zig build -Doptimize=ReleaseFast
# Binaries in zig-out/bin/: kuri  kuri-agent  kuri-fetch  kuri-browse

### Primeira execução, caminho mais curto```bash
# start the server; if CDP_URL is unset, kuri launches managed Chrome for you
./zig-out/bin/kuri

# discover tabs from that managed browser
curl -s http://127.0.0.1:8080/discover

# inspect the discovered tab list
curl -s http://127.0.0.1:8080/tabs

Existe também um wrapper experimental leve em `tools/kuri_harness.py` se você quiser auxiliares em Python sobre a mesma superfície HTTP.

Se você já tem o Chrome em execução com depuração remota, defina `CDP_URL` para o endpoint WebSocket ou HTTP:```bash
CDP_URL=ws://127.0.0.1:9222/devtools/browser/... ./zig-out/bin/kuri
# or
CDP_URL=http://127.0.0.1:9222 ./zig-out/bin/kuri

---

## 🌐 HTTP API

Todos os endpoints retornam JSON. Autenticação opcional via variável de ambiente `KURI_SECRET`. **135 endpoints** — paridade total com agent-browser e browser-use.

### Núcleo

| Caminho | Descrição |
|------|-------------|
| `GET /health` | Status do servidor, contagem de abas, versão |
| `GET /tabs` | Lista todas as abas registradas |
| `GET /discover` | Descobre automaticamente abas do Chrome via CDP |
| `GET /tab/current` | Obtém ou define a aba atual para uma `X-Kuri-Session` |
| `GET /page/info` | URL/título/ready-state/viewport/scroll em tempo real da aba ativa |
| `GET /page/state` | Observação compacta da página: url, título, scroll%, viewport, contagens de formulários/links/imagens/inputs |
| `POST /batch` | Executa vários comandos em uma única chamada HTTP — retorna uma matriz de resultados |
| `GET /browdie` | 🌰 (easter egg) |

### Controle do Navegador

| Caminho | Parâmetros | Descrição |
|------|--------|-------------|
| `GET /navigate` | `tab_id`, `url` | Navega a aba para a URL |
| `GET /tab/new` | `url`, `activate`, `wait` | Cria uma nova aba e opcionalmente hidrata/define a aba atual |
| `GET /tab/close` | `tab_id` | Fecha uma aba |
| `GET /window/new` | `url`, `activate`, `wait` | Cria um novo alvo de janela/aba |
| `GET /snapshot` | `tab_id`, `filter`, `format` | Snapshot da árvore a11y com refs `eN`. Use `filter=interactive&format=compact` para loops de agente com baixo consumo de tokens. |
| `GET /text` | `tab_id` | Extrai o texto da página |
| `GET /screenshot` | `tab_id`, `format`, `quality`, `save` | Captura screenshot (base64); `save=true` grava o PNG em `STATE_DIR/screenshots` e retorna `{path,bytes}` em vez disso |
| `GET /screenshot/annotated` | `tab_id` | Screenshot com rótulos numerados de elementos |
| `GET /screenshot/diff` | `tab_id`, `baseline` | Diff visual entre a screenshot atual e a de referência |
| `GET /action` | `tab_id`, `ref`, `action`, `value` | Click/type/fill/select/scroll/hover/dblclick/check/uncheck/blur por ref |
| `GET /evaluate` | `tab_id`, `expression` | Executa JavaScript |
| `GET /evalhandle` | `tab_id`, `expression` | Executa JS, retorna o handle objectId (não o valor) |
| `GET /close` | `tab_id` | Fecha aba + limpeza |
| `GET /bringtofront` | `tab_id` | Traz a aba para a frente |

### Ações

| Caminho | Parâmetros | Descrição |
|------|--------|-------------|
| `GET /clear` | `ref` | Limpa o valor do campo de entrada |
| `GET /selectall` | `ref` | Seleciona todo o texto em input/contenteditable |
| `GET /setvalue` | `ref`, `value` | Define o valor do campo de entrada diretamente (ignora eventos de teclado) |
| `GET /dispatch` | `ref`, `type` | Despacha evento DOM personalizado no elemento |
| `GET /boundingbox` | `ref` | Obtém o retângulo delimitador do elemento (x, y, width, height, centerX, centerY) |
| `GET /getattribute` | `ref`, `name` | Obtém o atributo do elemento pelo nome |
| `GET /inputvalue` | `ref` | Obtém o valor atual do elemento de entrada |
| `GET /element/state` | `ref`, `check` | Booleano rápido: `exists`, `visible`, `enabled`, `checked` |
| `GET /find-element` | `text`/`role`/`label`/`placeholder`/`testid` | Localizador semântico — encontra o elemento sem snapshot |
| `GET /highlight` | `ref` ou `selector` | Destaca o elemento com sobreposição |

### Mouse e Toque

| Caminho | Parâmetros | Descrição |
|------|--------|-------------|
| `GET /mouse/move` | `x`, `y` | Move o mouse para as coordenadas |
| `GET /mouse/down` | `x`, `y`, `button` | Botão do mouse pressionado |
| `GET /mouse/up` | `x`, `y`, `button` | Botão do mouse solto |
| `GET /mouse/wheel` | `x`, `y`, `deltaX`, `deltaY` | Rolagem da roda do mouse |
| `GET /tap` | `x`, `y` | Toque (touchStart + touchEnd) |
| `GET /swipe` | `startX`, `startY`, `endX`, `endY` | Gesto de deslize por toque |
| `GET /drag` | `src_ref`, `tgt_ref` | Arrasta o elemento até o alvo |

### Teclado

| Caminho | Parâmetros | Descrição |
|------|--------|-------------|
| `GET /keyboard/type` | `tab_id`, `text` | Digita texto via eventos de teclado |
| `GET /keyboard/inserttext` | `tab_id`, `text` | Insere texto diretamente |
| `GET /keydown` | `tab_id`, `key` | Evento de tecla pressionada |
| `GET /keyup` | `tab_id`, `key` | Evento de tecla solta |

### Extração de Conteúdo

| Caminho | Descrição |
|------|-------------|
| `GET /markdown` | Converte página para Markdown |
| `GET /links` | Extrai todos os links |
| `GET /dom/query` | Consulta de seletor CSS |
| `GET /dom/html` | Obtém o HTML do elemento |
| `GET /dom/attributes` | Obtém os atributos do elemento |
| `GET /pdf` | Imprime a página em PDF |
| `GET /find` | Pesquisa de texto na página |

### Aguardando

| Caminho | Parâmetros | Descrição |
|------|--------|-------------|
| `GET /wait` | `selector`, `text`, `url`, `state`, `visible`, `timeout` | Aguarda seletor/texto/padrão de URL/networkidle/estado de carregamento |
| `GET /wait/function` | `expression`, `timeout` | Aguarda até que uma expressão JS arbitrária seja truthy |
| `GET /wait/download` | `timeout` | Aguarda a conclusão do download do arquivo |

### Tratamento de Diálogos

| Caminho | Descrição |
|------|-------------|
| `GET /dialog/auto` | Lida automaticamente com todos os diálogos JS (aceitar ou dispensar) |
| `GET /dialog/accept` | Aceita o diálogo atual (com texto de prompt opcional) |
| `GET /dialog/dismiss` | Dispensa o diálogo atual |

### Rede e HAR

| Caminho | Descrição |
|------|-------------|
| `GET /har/start` | Inicia a gravação do tráfego de rede |
| `GET /har/stop` | Para e retorna o JSON HAR 1.2 |
| `GET /har/status` | Estado da gravação + contagem de entradas |
| `GET /har/replay` | Mapa da API com trechos de código curl/fetch/python |
| `GET /cookies` | Obtém cookies |
| `GET /cookies/set` | Define cookies |
| `GET /cookies/delete` | Exclui cookies |
| `GET /cookies/clear` | Limpa todos os cookies |
| `GET /headers` | Define cabeçalhos de requisição personalizados |
| `GET /intercept/start` | Inicia a interceptação de requisições |
| `GET /intercept/stop` | Para a interceptação de requisições |
| `GET /intercept/requests` | Lista requisições interceptadas |
| `GET /request/detail` | Obtém o corpo da resposta para um ID de requisição |
| `GET /response/body` | Busca a URL e retorna o corpo da resposta |
| `GET /network` | Estatísticas de tráfego de rede |
| `GET /download` | Dispara o download de arquivo |

### Navegação e Estado

| Caminho | Descrição |
|------|-------------|
| `GET /back` | Voltar no navegador |
| `GET /forward` | Avançar no navegador |
| `GET /reload` | Recarrega a página |
| `GET /stop` | Para o carregamento da página |
| `GET /pushstate` | Navegação SPA via history.pushState |
| `GET /storage/local` | Obtém/define localStorage |
| `GET /storage/session` | Obtém/define sessionStorage |
| `GET /storage/local/clear` | Limpa localStorage |
| `GET /storage/session/clear` | Limpa sessionStorage |
| `GET /session/save` | Salva a sessão do navegador |
| `GET /session/load` | Restaura a sessão do navegador |
| `GET /session/list` | Lista sessões salvas |
| `GET /setcontent` | Define o HTML da página diretamente (POST) |

### Perfis de Autenticação

| Caminho | Descrição |
|------|-------------|
| `GET /auth/profile/save` | Salva cookies + storage como um perfil de autenticação nomeado |
| `GET /auth/profile/load` | Restaura um perfil de autenticação nomeado em uma aba |
| `GET /auth/profile/list` | Lista perfis de autenticação salvos |
| `GET /auth/profile/delete` | Exclui um perfil de autenticação salvo |
| `GET /auth/extract` | Extrai tokens de autenticação (JWT, cookies, headers) |
| `GET /set/credentials` | Define credenciais de autenticação básica HTTP |

No macOS, os segredos do perfil de autenticação são armazenados no Keychain do usuário.

### Emulação

| Caminho | Parâmetros | Descrição |
|------|--------|-------------|
| `GET /emulate` | tipo de dispositivo, tamanho de tela | Emulação de dispositivo |
| `GET /set/viewport` | `width`, `height` | Define o tamanho do viewport |
| `GET /set/useragent` | `ua` | Define o user agent |
| `GET /set/media` | `media` | Emula o tipo de mídia |
| `GET /set/offline` | `offline` | Alterna o modo offline |
| `GET /geolocation` | `lat`, `lng` | Substitui a geolocalização |
| `GET /timezone` | `timezone` | Substitui o fuso horário (ex.: `America/New_York`) |
| `GET /locale` | `locale` | Substitui o locale (ex.: `en-US`) |
| `GET /permissions` | `name`, `state` | Concede/nega permissões (geolocalização, notificações, área de transferência) |

### Scripts e Injeção

| Caminho | Descrição |
|------|-------------|
| `GET /script/inject` | Injeta JavaScript na página (persiste entre navegações) |
| `GET /initscript/remove` | Remove um script init injetado anteriormente |
| `GET /addstyle` | Injeta folha de estilo CSS |
| `GET /expose` | Expõe uma função nomeada ao contexto JS da página |

### Inspeção React

| Caminho | Descrição |
|------|-------------|
| `GET /react/tree` | Árvore de componentes React via hook do DevTools |
| `GET /react/inspect` | Props e estado de componentes React |
| `GET /react/renders` | Rastreamento de renderização React (iniciar/parar) |
| `GET /react/suspense` | Status do limite Suspense do React |

### Gravação e Desempenho

| Caminho | Descrição |
|------|-------------|
| `GET /recording/start` | Grava ações do usuário (clique, entrada, navegação) |
| `GET /recording/stop` | Para a gravação + retorna o log de ações |
| `GET /vitals` | Core Web Vitals (LCP, CLS, FID, TTFB, FCP, domInteractive) |
| `GET /perf/lcp` | Tempo do Largest Contentful Paint |
| `GET /trace/start` | Inicia o trace de desempenho |
| `GET /trace/stop` | Para o trace |
| `GET /profiler/start` | Inicia o profiler JS |
| `GET /profiler/stop` | Para o profiler |

### Depuração

| Caminho | Descrição |
|------|-------------|
| `GET /debug/enable` | Ativa o HUD de depuração na página e o modo de congelamento opcional |
| `GET /debug/disable` | Desativa o HUD de depuração na página |
| `GET /inspect` | Inspeção de elemento |
| `GET /errors` | Coleta erros JS |
| `GET /console` | Lê os logs do console |
| `GET /frames` | Lista os frames da página |
| `GET /frame` | Alterna para o contexto do iframe por nome ou URL |
| `GET /mainframe` | Volta para o frame principal |
| `GET /diff/snapshot` | Diff compacto `+`/`~`/`-` em relação à chamada anterior para esta aba — o loop de ações eficiente em tokens (com alias `/snapshot/changes`). Em mudanças em massa, recorre a um snapshot completo com um cabeçalho `! page replaced`. |
| `GET /diff/url` | Compara duas URLs lado a lado (navegar, snapshot, diff) |

### Streaming

| Caminho | Descrição |
|------|-------------|
| `GET /screencast/start` | Inicia a gravação de tela |
| `GET /screencast/stop` | Para a gravação de tela |
| `GET /video/start` | Inicia a captura de vídeo |
| `GET /video/stop` | Para a captura de vídeo |
| `GET /ws/start` | Inicia o túnel WebSocket |
| `GET /ws/stop` | Para o túnel WebSocket |

### Loop amigável para agentes

O loop de servidor com menor atrito é:

1. `GET /tab/new?url=...`
2. `GET /page/state` (leve) ou `GET /snapshot?filter=interactive&format=compact` (completo)
3. `GET /action?action=click&ref=eN`
4. Repita — ou use `POST /batch` para operações de várias etapas em uma única chamada

Os parâmetros de consulta `url` e `expression` são decodificados via percent-encoding. Envie `X-Kuri-Session: my-agent` para persistir o contexto da aba no lado do servidor.

---

## 🧠 Habilidades

O repositório inclui uma área de habilidades extensível pelo usuário:

- `skills/kuri-skill.md` é a habilidade base do agente HTTP Kuri
- `skills/custom/` é reservado para suas próprias habilidades específicas do projeto
- `skills/custom/hackernews-page-2.md` é um exemplo concreto de habilidade personalizada
- `.claude/skills/kuri-server/SKILL.md` permanece sincronizado para habilidades de repositório no estilo Claude

A habilidade base agora também explica qual caminho de navegador usar:

- `kuri` API HTTP: automação de Chrome/CDP em produção com sessões, snapshots, ações, HAR, cookies e screenshots
- `kuri-fetch`: extração de fetch/texto independente, sem Chrome
- `kuri-browse`: navegação interativa via terminal
- `kuri-agent`: automação CLI via script contra o servidor Kuri
- `kuri-browser/`: runtime de navegador experimental separado, nativo em Zig, para trabalho de paridade

Para o CLI experimental do navegador:```bash
cd kuri-browser
zig build run -- render https://news.ycombinator.com --selector ".titleline a" --dump text
zig build run -- render https://todomvc.com/examples/react/dist/ --js --wait-eval "document.querySelectorAll('.todo-list li').length >= 1"
zig build run -- parity --offline
zig build run -- bench --offline
zig build run -- serve-cdp --port 9333

`--compress` captura uma linha de base PNG e um candidato JPEG, grava o arquivo menor e relata a economia de bytes. Medição local atual em `https://example.com`: `20.523` bytes PNG para `18.183` bytes JPEG qualidade 50, economizando `2.340` bytes ou `11%`.

### Avançado

| Path | Descrição |
|------|-------------|
| `GET /diff/snapshot` | Delta compacto `+`/`~`/`-` em relação ao snapshot anterior (loop de ação do agente) |
| `GET /emulate` | Emulação de dispositivo |
| `GET /geolocation` | Definir geolocalização |
| `POST /upload` | Upload de arquivo |
| `GET /script/inject` | Injetar JavaScript |
| `GET /intercept/start` | Iniciar interceptação de requisições |
| `GET /intercept/stop` | Parar interceptação |
| `GET /screenshot/annotated` | Captura de tela com anotações de elementos |
| `GET /screenshot/diff` | Diferença visual entre capturas de tela |
| `GET /screencast/start` | Iniciar screencast |
| `GET /screencast/stop` | Parar screencast |
| `GET /video/start` | Iniciar gravação de vídeo |
| `GET /video/stop` | Parar gravação de vídeo |
| `GET /console` | Obter mensagens do console |
| `GET /stop` | Parar carregamento da página |
| `GET /get` | Busca HTTP direta (lado do servidor) |
| `GET /scrollintoview` | Rolar até um elemento referenciado ficar visível |
| `GET /drag` | Arrastar de uma referência para outra |
| `GET /keyboard/type` | Digitar texto com eventos de tecla |
| `GET /keyboard/inserttext` | Inserir texto diretamente |
| `GET /keydown` | Disparar evento keydown |
| `GET /keyup` | Disparar evento keyup |
| `GET /wait` | Aguardar estado de prontidão ou condições do elemento |
| `GET /tab/close` | Fechar uma aba |
| `GET /highlight` | Destacar um elemento por referência ou seletor |
| `GET /errors` | Obter erros de página/execução |
| `GET /set/offline` | Alternar emulação de rede offline |
| `GET /set/media` | Definir recursos de mídia emulados |
| `GET /set/credentials` | Definir credenciais de autenticação básica HTTP |
| `GET /find` | Encontrar correspondências de texto na página atual |
| `GET /trace/start` | Iniciar tracing do Chrome |
| `GET /trace/stop` | Parar tracing e retornar dados de trace |
| `GET /profiler/start` | Iniciar profiler JS |
| `GET /profiler/stop` | Parar profiler JS |
| `GET /inspect` | Inspecionar um elemento ou estado da página |
| `GET /set/viewport` | Definir tamanho do viewport |
| `GET /set/useragent` | Substituir user agent |
| `GET /dom/attributes` | Obter atributos do elemento |
| `GET /frames` | Listar árvore de frames |
| `GET /network` | Inspecionar estado/requisições de rede |

---

## 🛡️ Furtividade e Evasão de Bots

A Kuri aplica patches anti-detecção automaticamente na inicialização — nenhuma configuração manual é necessária.

### O que é aplicado

- **`Page.addScriptToEvaluateOnNewDocument`** — patches de stealth são executados antes de qualquer JS da página
- **`navigator.webdriver = false`** — oculta o sinalizador de automação no nível do Chromium (`--disable-blink-features=AutomationControlled`)
- **WebGL/Canvas/AudioContext spoofing** — derrota a detecção baseada em fingerprint
- **UA rotation** — 5 user agents realistas do Chrome/Safari/Firefox
- **chrome.csi/chrome.loadTimes** — stubs para verificações específicas da Akamai

### Detecção de bloqueio de bot

Navigate detecta automaticamente bloqueios e retorna fallback estruturado:```bash
curl -s "http://localhost:8080/navigate?tab_id=ABC&url=https://protected-site.com"
# If blocked:
# {"blocked":true,"blocker":"akamai","ref_code":"0.7d...",
#  "fallback":{"suggestions":["Open URL directly in browser","Use KURI_PROXY"]}}
# If ok: normal CDP response

### Sites testados

| Site | Proteção | Resultado |
|------|-----------|--------|
| Singapore Airlines | Akamai WAF | ✅ Contornado (era bloqueado antes da v0.4.0) |
| Shopee SG | Antifraude personalizado | ✅ Página carrega, redireciona para login |
| Google Flights | Nenhuma | ✅ Interação completa |
| Booking.com | PerimeterX | ⚠️ Precisa de proxy |

---

## 🔧 kuri-fetch

Buscador HTTP autônomo — sem Chrome, sem Playwright, sem npm. Vem como um binário de ~2 MB com QuickJS embutido para execução de JS.```bash
zig build fetch    # build + run

# Default: convert to Markdown
kuri-fetch https://example.com

# Extract links
kuri-fetch -d links https://news.ycombinator.com

# Structured JSON output
kuri-fetch --json https://example.com

# Execute inline scripts via QuickJS
kuri-fetch --js https://example.com

# Write to file, quiet mode
kuri-fetch -o page.md -q https://example.com

# Pipe-friendly: content → stdout, status → stderr
kuri-fetch -d text https://example.com | wc -w

I don't see any source text to translate — the INPUT section is empty. Please provide the chunk content to translate.```
🌰 kuri-browse — terminal browser
→ loading https://example.com

# Example Domain
This domain is for use in documentation examples...
Learn more [1]

───── Links ─────
  [1] https://iana.org/domains/example

✓ 528 bytes, 1 links (133ms)
[nav] https://example.com> 1     ← type 1 to follow the link

### Comandos

| Comando | Descrição |
|---------|-------------|
| `tabs [--port N]` | Listar abas do Chrome |
| `use <ws_url>` | Anexar a uma aba (salva a sessão) |
| `open [url] [--port N]` | Abrir uma nova aba (opcionalmente navegando para a URL) |
| `status` | Mostrar a sessão atual |
| `go <url>` | Navegar para URL |
| `snap [--interactive] [--json] [--text] [--depth N]` | Snapshot de acessibilidade, salva refs `eN` |
| `click <ref>` | Clicar no elemento por ref (eventos de mouse CDP, compatível com React) |
| `type <ref> <text>` | Digitar no elemento (eventos de tecla por caractere, compatível com React) |
| `fill <ref> <text>` | Preencher o valor do input |
| `select <ref> <value>` | Selecionar opção do dropdown |
| `hover <ref>` | Passar o mouse sobre o elemento |
| `focus <ref>` | Focar o elemento |
| `scroll` | Rolar a página |
| `viewport [width height]` | Obter ou definir dimensões da viewport |
| `eval <js>` | Avaliar JavaScript |
| `text [selector]` | Obter o texto da página |
| `shot [--out file.png]` | Captura de tela |
| `back` | Navegar de volta |
| `forward` | Navegar para frente |
| `reload` | Recarregar a página atual |
| `cookies` | Listar cookies com sinalizadores de segurança |
| `headers` | Verificar cabeçalhos de resposta de segurança |
| `audit` | Auditoria de segurança completa |
| `storage [local\|session\|all]` | Despejar localStorage / sessionStorage |
| `jwt` | Extrair e decodificar JWTs de cookies e do armazenamento |
| `fetch <method> <url> [--data <json>]` | Fetch autenticado usando cookies da página |
| `probe <url-template> <start> <end>` | Teste de IDOR: iterar IDs numéricos na URL |
| `grab <ref>` | Clicar na ref, interceptar `window.open`, seguir redirecionamento na mesma aba |
| `wait-for-tab [--port N]` | Verificar periodicamente uma nova aba, alternar a sessão automaticamente |
| `stealth` | Aplicar patches anti-detecção |
| `set-header <name> <value>` | Adicionar um cabeçalho personalizado a todas as requisições |
| `show-headers` | Mostrar cabeçalhos extras armazenados |
| `clear-headers` | Remover todos os cabeçalhos extras |
---

## 📱 kuri-mobile (iOS + Android)

CLI nativo em Zig para controlar simuladores iOS, iPhones reais (listagem + iniciar/encerrar) e dispositivos/emuladores Android — inspirado em [`mobile-device-mcp`](https://github.com/srmorete/mobile-device-mcp), reimplementado em Zig sem Bun/Node/Gradle/Xcode no caminho de build.```bash
cd kuri-mobile && zig build && cp zig-out/bin/kuri-mobile ../zig-out/bin/

# The main `kuri` binary forwards android/ios subcommands to kuri-mobile:
kuri ios list-devices                              # sims + real devices (usbmuxd, native)
kuri ios openurl https://example.com               # navigate Safari
kuri ios screenshot out.png                        # auto-picks booted sim
kuri ios launch com.apple.Preferences

kuri android list-devices                          # native Zig adb wire-protocol client
kuri android tap 540 1200
kuri android swipe 100 1500 100 500
kuri android screenshot phone.png
kuri android uitree                                # flat element list via uiautomator dump

**Auditoria de cabeçalhos** — verifique quais cabeçalhos de segurança o alvo envia:```bash
kuri-agent go https://target.example.com
kuri-agent headers
# → {"url":"https://...","status":200,"headers":{
#     "content-security-policy":"default-src 'self'",
#     "strict-transport-security":"max-age=31536000",
#     "x-frame-options":"(missing)",
#     "x-content-type-options":"nosniff", ...}}

**Trajetória cross-account** — use `eval` para reproduzir chamadas de API com tokens diferentes:```bash
# After login, grab the auth token from localStorage
kuri-agent eval "localStorage.getItem('token')"

# Probe a resource ID with the current session
kuri-agent eval "fetch('/api/assessments/42').then(r=>r.status)"

# Check for IDOR: does a different user's resource return 200 or 403?
kuri-agent eval "fetch('/api/assessments/99').then(r=>r.status)"

---

## 🏗 Arquitetura```
┌──────────────────────────────────────────────────────────┐
│                     HTTP API Layer                        │
│         (std.http.Server, thread-per-connection)          │
├──────────────┬──────────────────┬────────────────────────┤
│   Browser    │  Crawler Engine  │   kuri-fetch / browse   │
│   Bridge     │                  │   (standalone CLIs)     │
├──────────────┼──────────────────┼────────────────────────┤
│ CDP Client   │ URL Validator    │ std.http.Client         │
│ Tab Registry │ HTML→Markdown    │ QuickJS JS Engine       │
│ A11y Snapshot│ Link Extractor   │ DOM Stubs (Layer 3)     │
│ Ref Cache    │ Text Extractor   │ SSRF Validator          │
│ HAR Recorder │                  │ Colored Renderer        │
│ Stealth JS   │                  │ History + REPL          │
├──────────────┴──────────────────┴────────────────────────┤
│  Chrome Lifecycle Manager                                 │
│  (launch, health-check, auto-restart, port detection)     │
└──────────────────────────────────────────────────────────┘

---

## ⚙️ Configuração

| Env Var | Padrão | Descrição |
|---------|--------|-----------|
| `HOST` | `127.0.0.1` | Endereço de bind do servidor |
| `PORT` | `8080` | Porta do servidor |
| `CDP_URL` | *(nenhum)* | Conectar a um Chrome existente (`ws://...` ou `http://127.0.0.1:9222`) |
| `KURI_SECRET` | *(nenhum)* | Segredo de autenticação para requisições de API |
| `STATE_DIR` | `.kuri` | Diretório de estado da sessão |
| `REQUEST_TIMEOUT_MS` | `30000` | Timeout de requisição HTTP |
| `NAVIGATE_TIMEOUT_MS` | `30000` | Timeout de navegação |
| `STALE_TAB_INTERVAL_S` | `30` | Intervalo de limpeza de abas obsoletas |
| `NO_COLOR` | *(nenhum)* | Desativar saída CLI colorida |

---

## 💰 Custo de Tokens

Para uma tarefa de monitoramento de 50 páginas (dos benchmarks do Pinchtab):

| Método | Tokens | Custo ($) | Melhor para |
|--------|--------|-----------|-------------|
| `/text` | ~40.000 | $0,20 | Leitura intensiva (13× mais barato que capturas de tela) |
| `/snapshot?filter=interactive&format=compact` | ~40.000 | $0,20 | Interação de elementos com baixo uso de tokens |
| `/snapshot` (completo) | ~525.000 | $2,63 | Compreensão completa da página |
| `/screenshot` | ~100.000 | $1,00 | Verificação visual |

---

## 🤝 Contribuindo

Abra uma issue antes de enviar um PR grande para podermos alinhar a abordagem.

---```bash
git clone https://github.com/justrach/kuri.git
cd kuri
zig build test         # 252+ tests must pass
zig build test-fetch   # kuri-fetch tests (69 tests)
zig build test-browse  # kuri-browse tests (22 tests)