justrach/kuriAutomazione del browser, web crawling e controllo di dispositivi iOS + Android per agenti AI. Snapshot CDP nativi Zig ed efficienti in termini di token, registrazione HAR, client nativo del protocollo wire di adb e fetcher autonomo.
<p align="center">
<img src="https://assets.kitploit.com/production/public/readmes/13639/7915bba5fb25229c11f59482cfcd4a0eaf2945ee066dbf5cec395df880b53268.png" alt="Kuri" width="200" />
</p>
<h1 align="center">Kuri 🌰</h1>
<p align="center">
<a href="https://kuri.trilok.ai/download/latest.json"><img src="https://img.shields.io/badge/stable-v0.6.1-brightgreen?style=flat-square" alt="Stable release"></a>
<a href="https://github.com/justrach/kuri/blob/main/LICENSE"><img src="https://img.shields.io/github/license/justrach/kuri?style=flat-square" alt="License"></a>
<img src="https://img.shields.io/badge/zig-0.16.0-f7a41d?style=flat-square" alt="Zig">
<img src="https://img.shields.io/badge/node__modules-0_files-brightgreen?style=flat-square" alt="node_modules">
<img src="https://img.shields.io/badge/status-stable-brightgreen?style=flat-square" alt="status">
</p>
## Installazione
```sh
curl -fsSL https://kuri.trilok.ai/download | sh
```
macOS arm64/x86_64 e Linux x86_64/arm64. Binario singolo, nessuna dipendenza runtime.
Download diretti: [macOS arm64](https://kuri.trilok.ai/download/v0.6.1/kuri-v0.6.1-aarch64-macos.tar.gz) · [macOS x86_64](https://kuri.trilok.ai/download/v0.6.1/kuri-v0.6.1-x86_64-macos.tar.gz) · [Linux x86_64](https://kuri.trilok.ai/download/v0.6.1/kuri-v0.6.1-x86_64-linux.tar.gz) · [Linux arm64](https://kuri.trilok.ai/download/v0.6.1/kuri-v0.6.1-aarch64-linux.tar.gz)
---
**Automazione browser e web crawling per agenti AI. Scritto in Zig. Zero Node.js.**
Automazione CDP · Snapshot A11y · Registrazione HAR · Fetcher standalone · Browser terminale interattivo · CLI agentica · Security testing · Controllo dispositivi iOS + Android
[Quick Start](#-quick-start) · [Benchmarks](#-benchmarks) · [kuri-agent](#-kuri-agent) · [Security Testing](#-security-testing) · [API](#-http-api) · [Skills](#-skills) · [Changelog](https://github.com/justrach/kuri/blob/main/CHANGELOG.md)
> **Perché i team passano a Kuri:** le build `ReleaseFast` attuali per Apple Silicon restano sotto i 2 MB per binario, e una nuova esecuzione di Google Flights il 2026-04-23 ha misurato **3.392 token** per un ciclo completo di `kuri-agent` (`go→snap→click→snap→eval`). I delta tra strumenti dovrebbero essere rieseguiti nello stesso ambiente prima di citare una percentuale.
---
## Perché Kuri Vince per gli Agenti
La maggior parte degli strumenti per browser è stata creata per ingegneri QA. Kuri è costruito per i cicli degli agenti: leggere la pagina, mantenere basso il costo in token, agire su riferimenti stabili e andare avanti.
- **135 endpoint HTTP** — piena parità con agent-browser e browser-use, dall'ispezione React ai Core Web Vitals.
- **7-12% in meno di token** rispetto ad agent-browser su pagine reali grazie al formato di riferimento `@eN` e al rendering senza prefissi.
- **Osservazioni 44 volte più leggere** con `/page/state` (48 token) rispetto allo snapshot completo (2.124 token) per la stessa pagina di Google Flights.
- **Esecuzione batch** — `POST /batch` invia N comandi in una singola chiamata HTTP, eliminando N-1 round-trip e N-1 turni LLM.
- **Compatibile con React** — eventi mouse CDP affidabili ed eventi tastiera per carattere attivano `onClick` e `onChange` di React 18/19.
### Token degli snapshot: Google Flights `SIN → TPE`
Nuova esecuzione il 2026-05-24 in questo workspace, misurata con `wc -c` e approssimazione `chars/4`.
| Strumento / Modalità | Caratteri | ~Token | Nota |
|---|---:|---:|---|
| `kuri snap` (completo) | 8.499 | **2.124** | Tutti i nodi + riferimenti interattivi |
| `kuri snap` (solo interattivi) | ~3.000 | **~750** | Ideale per i cicli degli agenti |
| `kuri /page/state` | 190 | **48** | Osservazione leggera (url, title, scroll%, conteggi) |
| agent-browser snap (stimato) | ~9.183 | **~2.295** | Overhead del formato `[ref=e0]` |
### Efficienza dei token: kuri vs agent-browser
| Pagina | token kuri | token agent-browser | Risparmio |
|---|---:|---:|---|
| example.com | 40 | 35 | -13% (pagina banale, agent-browser salta la root) |
| Hacker News | 386 | ~440 | **12% in meno** |
| Google Flights SIN→TPE | 2.124 | ~2.295 | **7% in meno** |
Il risparmio deriva dal formato compatto di kuri:
- riferimenti `@e0` (3 caratteri) vs `[ref=e0]` (9 caratteri)
- Nessun prefisso `- ` per riga (risparmia 2 caratteri × numero di righe)
- Stessa indentazione, stesso filtraggio dei nodi
### Costo completo del workflow: `go → snap → click → snap → eval`
| Strumento | Token per ciclo |
|---|---:|
| **kuri-agent** | **~3.400** |
| Con `/page/state` invece del secondo snap | **~1.700** |
| Con `POST /batch` (tutto in una chiamata) | **~1.700** (stessi token, 1 chiamata HTTP invece di 5) |
### kuri vs libretto
[libretto](https://github.com/saffron-health/libretto) (Playwright + Node) è il concorrente più vicino sul costo in token per passo. Misurato testa a testa il 2026-07-04 — stesso Chrome, stessa scheda, conteggi reali `tiktoken` `o200k_base` (metodologia completa e riproduzione: **[benchmarks/libretto_comparison.md](https://github.com/justrach/kuri/blob/main/benchmarks/libretto_comparison.md)**). La divisione onesta:
| Asse | Vincitore | Dettaglio |
|---|---|---|
| Latenza per chiamata | **kuri** | 4–117 ms vs 1.344–1.500 ms (**13–376× più veloce** — server persistente vs Node-per-comando) |
| Token snapshot, pagina tipica | **kuri** | semplice 61 vs 151 (2,5×), articolo 265 vs 363 (1,37×) — grammatica più compatta |
| Token snapshot, lista grande | pari | kuri default 4.424 vs 813 — kuri emette tutti i 259 riferimenti, libretto tronca per default. Con `limit=5` kuri renderizza 555 token (**1,46× sotto libretto**), 34 riferimenti + marcatori `… +45 more` |
| Traiettoria (feed, 9 click) | **kuri**, di poco | 898 vs 939 token (base `limit=5` + ciclo diff vs ciclo exec) — parità o leggero vantaggio; la perdita di 5,1× del mattino era la base non troncata |
| Esecuzioni ripetute | **libretto** | compila le traiettorie in uno script Playwright → replay a 0 token; kuri ripaga il ciclo a ogni esecuzione |
**Cosa ha guadagnato kuri studiando libretto** (tutto rilasciato in questa versione): un ciclo diff-first (`take_snapshot_diff`, ~38 token/passo); un diff adattivo che ricade su uno snapshot completo con un'intestazione `! page replaced` in caso di navigazione; righe di rimozione solo per identità; screenshot scritti su disco (percorso restituito, i byte non entrano mai nel contesto); `get_page_state` su MCP; e — dopo aver riscritto `parseA11yNodes` come una vera visita DFS dell'albero — **troncamento opt-in delle liste** (`/snapshot?limit=N`, una riga `… +K more` per ogni esecuzione limitata), **ri-acquisizione con scope** (`scope=@ref`) e **indentazione gerarchica**, esposti anche come `uid`/`limit` su MCP `take_snapshot`. La traiettoria del feed con 9 click che costava 44.285 token con ingenui re-snapshot completi costa **898** con una base troncata + diff — 49× più economica, e oltre i 939 di libretto.
> Le tabelle più vecchie sopra usano un'approssimazione di token `chars/4`; il confronto con libretto usa conteggi reali `tiktoken`. Riesegui i numeri tra strumenti nel tuo ambiente prima di citare una percentuale.
### Dimensione del binario e memoria
Misurato su Apple M4 Pro, macOS 26.4.1. I binari attuali sono stati compilati con `-Doptimize=ReleaseFast`.
| Binario | Dimensione attuale |
|---|---:|
| `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) |
### L'RSS è rimasto stabile durante la migrazione a Zig 0.16
Misurato sulla build `ReleaseFast` attuale `v0.4.3` con `/usr/bin/time -l`.
| Comando | RSS massimo medio `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 |
## Il Problema
Ogni strumento di automazione browser trascina con sé Playwright (~300 MB), un runtime Node.js e una cascata di dipendenze npm. Il tuo agente AI vuole solo leggere una pagina, cliccare un pulsante e andare avanti.
**Kuri è un singolo binario Zig.** Quattro modalità, 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)
```
---
## 📦 Installazione
### Installazione con una riga (macOS / Linux)
```sh
curl -fsSL https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/install.sh | sh
```
Rileva la tua piattaforma, scarica il binario corretto, installa in `~/.local/bin`.
I download provengono dal branch `release-channel` autogestito di Kuri. I binari macOS sono firmati localmente con un certificato Developer ID. Gli asset di GitHub Release rispecchiano questi stessi tarball.
### bun / npm
```sh
bun install -g kuri-agent
# or: npm install -g kuri-agent
```
Scarica il binario nativo corretto per la tua piattaforma al momento dell'installazione.
### Canale di rilascio
I binari stabili di Kuri risiedono sul branch `release-channel` e vengono serviti direttamente dagli URL raw di GitHub.
- Installer stabile: `https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/install.sh`
- Manifest stabile: `https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/latest.json`
- Vista del branch: `https://github.com/justrach/kuri/tree/release-channel/stable`
- Schema di download diretto: `https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/<version>/kuri-<version>-<target>.tar.gz`
### Manuale
Scarica il tarball per la tua piattaforma dal [manifest della release stabile](https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/latest.json) o dalla [pagina GitHub Releases](https://github.com/justrach/kuri/releases) e estrailo nel tuo `$PATH`.
URL di installazione stabile:
```sh
curl -fsSL https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/install.sh | sh
```
Il manifest include URL esatti degli asset più checksum SHA-256 per `aarch64-linux`, `x86_64-linux`, `aarch64-macos` e `x86_64-macos`.
### Supporto piattaforme
| Piattaforma | Stato |
|---|---|
| macOS (`aarch64`, `x86_64`) | Binari precompilati, firmati + notarizzati |
| Linux (`aarch64`, `x86_64`) | Binari precompilati |
| Windows (`x86_64`) | **Sperimentale — solo cross-compile.** `zig build -Dtarget=x86_64-windows-gnu` è verificato in CI, ma l'automazione di Chrome, la demonizzazione, lo shutdown basato su segnali, la registrazione HAR e l'archivio di autenticazione su file sono tutti stub con `error.UnsupportedOnWindows` a runtime. Usa **WSL2** se hai bisogno del set di funzionalità reale. Tracciato in [#153](https://github.com/justrach/kuri/issues/153). |
Kuri si appoggia a primitive POSIX (`fork`, `clock_gettime`, socket grezzi) in diversi punti, quindi un porting nativo completo per Windows è un lavoro serio. La baseline a livello di compilazione sopra consente l'esecuzione dei percorsi `--version`/`--help` e delle operazioni puramente in memoria; le parti più complesse (Chrome, socket, daemonize) necessitano di implementazioni Win32 reali prima di uscire dalla lista degli stub. Se vuoi occuparti di una di queste, aggiungi +1 a [#153](https://github.com/justrach/kuri/issues/153) o apri una PR.
### Compilazione dai sorgenti
Richiede [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
```
---
## ⚡ Avvio rapido
**Requisiti:** [Zig ≥ 0.16.0](https://ziglang.org/download/) · Chrome/Chromium (per la modalità CDP)
```bash
git clone https://github.com/justrach/kuri.git
cd kuri
zig build # build everything
zig build test # run 252+ tests
# CDP mode — launches Chrome automatically
./zig-out/bin/kuri
# Standalone mode — no Chrome needed
./zig-out/bin/kuri-fetch https://example.com
# Interactive browser — browse from your terminal
./zig-out/bin/kuri-browse https://example.com
# Experimental standalone browser runtime — separate build, not production
(cd kuri-browser && zig build run -- render https://example.com)
(cd kuri-browser && zig build run -- bench --offline)
```
### Primo avvio, percorso più breve
```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
```
### Ciclo dell'agente basato sulla sessione
Per l'utilizzo HTTP in stile agente, preferisci un header di sessione insieme a `/tab/new`, `/page/info` e `/snapshot` invece di ripetere `tab_id` a ogni chiamata.
```bash
SESSION=hn-demo
BASE=http://127.0.0.1:8080
curl -s -H "X-Kuri-Session: $SESSION" \
"$BASE/tab/new?url=https%3A%2F%2Fnews.ycombinator.com"
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/page/info"
SNAP=$(curl -s -H "X-Kuri-Session: $SESSION" "$BASE/snapshot?filter=interactive&format=compact")
MORE_REF=$(printf '%s' "$SNAP" | python3 -c 'import re,sys; print(re.search(r"\"More\" @(e\\d+)", sys.stdin.read()).group(1))')
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/action?action=click&ref=$MORE_REF"
curl -s -H "X-Kuri-Session: $SESSION" "$BASE/page/info"
```
C'è anche un wrapper sperimentale minimale in `tools/kuri_harness.py` se desideri degli helper Python sopra la stessa superficie HTTP.
Se hai già Chrome in esecuzione con il debug remoto, imposta `CDP_URL` sull'endpoint WebSocket o 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
```
### Esplora vercel.com in 4 comandi
```bash
# 1. Discover Chrome tabs
curl -s http://localhost:8080/discover
# → {"discovered":1,"total_tabs":1}
# 2. Get tab ID
curl -s http://localhost:8080/tabs
# → [{"id":"ABC123","url":"chrome://newtab/","title":"New Tab"}]
# 3. Navigate
curl -s "http://localhost:8080/navigate?tab_id=ABC123&url=https://vercel.com"
# 4. Get accessibility snapshot (token-optimized for LLMs)
curl -s "http://localhost:8080/snapshot?tab_id=ABC123&filter=interactive"
# → [{"ref":"e0","role":"link","name":"VercelLogotype"},
# {"ref":"e1","role":"button","name":"Ask AI"}, ...]
```
---
## 🌐 HTTP API
Tutti gli endpoint restituiscono JSON. Autenticazione opzionale tramite la variabile d'ambiente `KURI_SECRET`. **135 endpoint** — piena parità con agent-browser e browser-use.
### Core
| Path | Descrizione |
|------|-------------|
| `GET /health` | Stato del server, numero di tab, versione |
| `GET /tabs` | Elenca tutte le tab registrate |
| `GET /discover` | Scopre automaticamente le tab di Chrome tramite CDP |
| `GET /tab/current` | Ottiene o imposta la tab corrente per un `X-Kuri-Session` |
| `GET /page/info` | URL/titolo/ready-state/viewport/scroll in tempo reale per la tab attiva |
| `GET /page/state` | Osservazione compatta della pagina: url, titolo, scroll%, viewport, conteggi di form/link/immagini/input |
| `POST /batch` | Esegue più comandi in una singola chiamata HTTP — restituisce un array di risultati |
| `GET /browdie` | 🌰 (easter egg) |
### Controllo del Browser
| Path | Parametri | Descrizione |
|------|--------|-------------|
| `GET /navigate` | `tab_id`, `url` | Naviga la tab all'URL specificato |
| `GET /tab/new` | `url`, `activate`, `wait` | Crea una nuova tab e opzionalmente la idrata/imposta come corrente |
| `GET /tab/close` | `tab_id` | Chiude una tab |
| `GET /window/new` | `url`, `activate`, `wait` | Crea un nuovo target finestra/tab |
| `GET /snapshot` | `tab_id`, `filter`, `format` | Snapshot dell'albero di accessibilità con riferimenti `eN`. Usa `filter=interactive&format=compact` per loop di agent a basso consumo di token. |
| `GET /text` | `tab_id` | Estrae il testo della pagina |
| `GET /screenshot` | `tab_id`, `format`, `quality`, `save` | Cattura uno screenshot (base64); `save=true` scrive il PNG in `STATE_DIR/screenshots` e restituisce invece `{path,bytes}` |
| `GET /screenshot/annotated` | `tab_id` | Screenshot con etichette numerate sugli elementi |
| `GET /screenshot/diff` | `tab_id`, `baseline` | Diff visivo tra lo screenshot corrente e quello di baseline |
| `GET /action` | `tab_id`, `ref`, `action`, `value` | Click/type/fill/select/scroll/hover/dblclick/check/uncheck/blur tramite ref |
| `GET /evaluate` | `tab_id`, `expression` | Esegue JavaScript |
| `GET /evalhandle` | `tab_id`, `expression` | Esegue JS, restituisce l'handle objectId (non il valore) |
| `GET /close` | `tab_id` | Chiude la tab + pulizia |
| `GET /bringtofront` | `tab_id` | Porta la tab in primo piano |
### Azioni
| Path | Parametri | Descrizione |
|------|--------|-------------|
| `GET /clear` | `ref` | Cancella il valore del campo di input |
| `GET /selectall` | `ref` | Seleziona tutto il testo in input/contenteditable |
| `GET /setvalue` | `ref`, `value` | Imposta direttamente il valore dell'input (aggira gli eventi di tastiera) |
| `GET /dispatch` | `ref`, `type` | Invia un evento DOM personalizzato sull'elemento |
| `GET /boundingbox` | `ref` | Ottiene il rect di delimitazione dell'elemento (x, y, width, height, centerX, centerY) |
| `GET /getattribute` | `ref`, `name` | Ottiene l'attributo dell'elemento per nome |
| `GET /inputvalue` | `ref` | Ottiene il valore corrente dell'elemento di input |
| `GET /element/state` | `ref`, `check` | Booleano rapido: `exists`, `visible`, `enabled`, `checked` |
| `GET /find-element` | `text`/`role`/`label`/`placeholder`/`testid` | Locator semantico — trova un elemento senza snapshot |
| `GET /highlight` | `ref` o `selector` | Evidenzia l'elemento con un overlay |
### Mouse e Touch
| Path | Parametri | Descrizione |
|------|--------|-------------|
| `GET /mouse/move` | `x`, `y` | Sposta il mouse alle coordinate specificate |
| `GET /mouse/down` | `x`, `y`, `button` | Pressione del pulsante del mouse |
| `GET /mouse/up` | `x`, `y`, `button` | Rilascio del pulsante del mouse |
| `GET /mouse/wheel` | `x`, `y`, `deltaX`, `deltaY` | Scroll con la rotellina del mouse |
| `GET /tap` | `x`, `y` | Tap touch (touchStart + touchEnd) |
| `GET /swipe` | `startX`, `startY`, `endX`, `endY` | Gesto di swipe touch |
| `GET /drag` | `src_ref`, `tgt_ref` | Trascina l'elemento sul target |
### Tastiera
| Path | Parametri | Descrizione |
|------|--------|-------------|
| `GET /keyboard/type` | `tab_id`, `text` | Digita testo tramite eventi di tastiera |
| `GET /keyboard/inserttext` | `tab_id`, `text` | Inserisce testo direttamente |
| `GET /keydown` | `tab_id`, `key` | Evento key down |
| `GET /keyup` | `tab_id`, `key` | Evento key up |
### Estrazione di Contenuti
| Path | Descrizione |
|------|-------------|
| `GET /markdown` | Converte la pagina in Markdown |
| `GET /links` | Estrae tutti i link |
| `GET /dom/query` | Query con selettore CSS |
| `GET /dom/html` | Ottiene l'HTML dell'elemento |
| `GET /dom/attributes` | Ottiene gli attributi dell'elemento |
| `GET /pdf` | Stampa la pagina in PDF |
| `GET /find` | Ricerca testuale nella pagina |
### Attesa
| Path | Parametri | Descrizione |
|------|--------|-------------|
| `GET /wait` | `selector`, `text`, `url`, `state`, `visible`, `timeout` | Attende selettore/testo/pattern URL/networkidle/stato di caricamento |
| `GET /wait/function` | `expression`, `timeout` | Attende che un'espressione JS arbitraria sia truthy |
| `GET /wait/download` | `timeout` | Attende il completamento del download di un file |
### Gestione dei Dialoghi
| Path | Descrizione |
|------|-------------|
| `GET /dialog/auto` | Gestisce automaticamente tutti i dialoghi JS (accetta o rifiuta) |
| `GET /dialog/accept` | Accetta il dialogo corrente (con testo prompt opzionale) |
| `GET /dialog/dismiss` | Rifiuta il dialogo corrente |
### Rete e HAR
| Path | Descrizione |
|------|-------------|
| `GET /har/start` | Avvia la registrazione del traffico di rete |
| `GET /har/stop` | Ferma e restituisce HAR 1.2 JSON |
| `GET /har/status` | Stato della registrazione + numero di voci |
| `GET /har/replay` | Mappa API con frammenti di codice curl/fetch/python |
| `GET /cookies` | Ottiene i cookie |
| `GET /cookies/set` | Imposta i cookie |
| `GET /cookies/delete` | Elimina i cookie |
| `GET /cookies/clear` | Cancella tutti i cookie |
| `GET /headers` | Imposta header di richiesta personalizzati |
| `GET /intercept/start` | Avvia l'intercettazione delle richieste |
| `GET /intercept/stop` | Ferma l'intercettazione delle richieste |
| `GET /intercept/requests` | Elenca le richieste intercettate |
| `GET /request/detail` | Ottiene il corpo della risposta per un ID richiesta |
| `GET /response/body` | Recupera l'URL e restituisce il corpo della risposta |
| `GET /network` | Statistiche del traffico di rete |
| `GET /download` | Attiva il download di un file |
### Navigazione e Stato
| Path | Descrizione |
|------|-------------|
| `GET /back` | Indietro nel browser |
| `GET /forward` | Avanti nel browser |
| `GET /reload` | Ricarica la pagina |
| `GET /stop` | Ferma il caricamento della pagina |
| `GET /pushstate` | Navigazione SPA tramite history.pushState |
| `GET /storage/local` | Ottiene/imposta localStorage |
| `GET /storage/session` | Ottiene/imposta sessionStorage |
| `GET /storage/local/clear` | Cancella localStorage |
| `GET /storage/session/clear` | Cancella sessionStorage |
| `GET /session/save` | Salva la sessione del browser |
| `GET /session/load` | Ripristina la sessione del browser |
| `GET /session/list` | Elenca le sessioni salvate |
| `GET /setcontent` | Imposta direttamente l'HTML della pagina (POST) |
### Profili di Autenticazione
| Path | Descrizione |
|------|-------------|
| `GET /auth/profile/save` | Salva cookie + storage come profilo di autenticazione con nome |
| `GET /auth/profile/load` | Ripristina un profilo di autenticazione con nome in una tab |
| `GET /auth/profile/list` | Elenca i profili di autenticazione salvati |
| `GET /auth/profile/delete` | Elimina un profilo di autenticazione salvato |
| `GET /auth/extract` | Estrae token di autenticazione (JWT, cookie, header) |
| `GET /set/credentials` | Imposta le credenziali di autenticazione HTTP basic |
Su macOS, i segreti dei profili di autenticazione sono memorizzati nel Keychain dell'utente.
### Emulazione
| Path | Parametri | Descrizione |
|------|--------|-------------|
| `GET /emulate` | tipo di dispositivo, dimensione schermo | Emulazione del dispositivo |
| `GET /set/viewport` | `width`, `height` | Imposta la dimensione del viewport |
| `GET /set/useragent` | `ua` | Imposta lo user agent |
| `GET /set/media` | `media` | Emula il tipo di media |
| `GET /set/offline` | `offline` | Attiva/disattiva la modalità offline |
| `GET /geolocation` | `lat`, `lng` | Sovrascrive la geolocalizzazione |
| `GET /timezone` | `timezone` | Sovrascrive il fuso orario (es. `America/New_York`) |
| `GET /locale` | `locale` | Sovrascrive la locale (es. `en-US`) |
| `GET /permissions` | `name`, `state` | Concede/nega permessi (geolocalizzazione, notifiche, clipboard) |
### Script e Iniezione
| Path | Descrizione |
|------|-------------|
| `GET /script/inject` | Inietta JavaScript nella pagina (persiste tra le navigazioni) |
| `GET /initscript/remove` | Rimuove uno script di init precedentemente iniettato |
| `GET /addstyle` | Inietta un foglio di stile CSS |
| `GET /expose` | Espone una funzione con nome al contesto JS della pagina |
### Ispezione React
| Path | Descrizione |
|------|-------------|
| `GET /react/tree` | Albero dei componenti React tramite l'hook DevTools |
| `GET /react/inspect` | Props e stato dei componenti React |
| `GET /react/renders` | Tracciamento dei render React (start/stop) |
| `GET /react/suspense` | Stato dei boundary Suspense di React |
### Registrazione e Performance
| Path | Descrizione |
|------|-------------|
| `GET /recording/start` | Registra le azioni dell'utente (click, input, navigate) |
| `GET /recording/stop` | Ferma la registrazione e restituisce il log delle azioni |
| `GET /vitals` | Core Web Vitals (LCP, CLS, FID, TTFB, FCP, domInteractive) |
| `GET /perf/lcp` | Timing del Largest Contentful Paint |
| `GET /trace/start` | Avvia la traccia delle performance |
| `GET /trace/stop` | Ferma la traccia |
| `GET /profiler/start` | Avvia il profiler JS |
| `GET /profiler/stop` | Ferma il profiler |
### Debug
| Path | Descrizione |
|------|-------------|
| `GET /debug/enable` | Abilita l'HUD di debug in-page e la modalità freeze opzionale |
| `GET /debug/disable` | Disabilita l'HUD di debug in-page |
| `GET /inspect` | Ispezione dell'elemento |
| `GET /errors` | Raccoglie gli errori JS |
| `GET /console` | Legge i log della console |
| `GET /frames` | Elenca i frame della pagina |
| `GET /frame` | Passa al contesto iframe per nome o URL |
| `GET /mainframe` | Torna al frame principale |
| `GET /diff/snapshot` | Diff compatto `+`/`~`/`-` rispetto alla chiamata precedente per questa tab — il loop di azioni efficiente in termini di token (alias di `/snapshot/changes`). In caso di modifiche massive, ricade su uno snapshot completo con un header `! page replaced`. |
| `GET /diff/url` | Confronta due URL affiancati (navigate, snapshot, diff) |
### Streaming
| Path | Descrizione |
|------|-------------|
| `GET /screencast/start` | Avvia la registrazione dello schermo |
| `GET /screencast/stop` | Ferma la registrazione dello schermo |
| `GET /video/start` | Avvia la cattura video |
| `GET /video/stop` | Ferma la cattura video |
| `GET /ws/start` | Avvio del tunnel WebSocket |
| `GET /ws/stop` | Arresto del tunnel WebSocket |
### Loop ottimizzato per gli agent
Il loop server a minor attrito è:
1. `GET /tab/new?url=...`
2. `GET /page/state` (leggero) o `GET /snapshot?filter=interactive&format=compact` (completo)
3. `GET /action?action=click&ref=eN`
4. Ripeti — oppure usa `POST /batch` per operazioni multi-step in una sola chiamata
I parametri di query `url` e `expression` sono percent-decoded. Invia `X-Kuri-Session: my-agent` per persistere il contesto della tab lato server.
---
## 🧠 Skills
Il repository include un'area di skill estensibile dall'utente:
- `skills/kuri-skill.md` è la skill di base per l'agent HTTP Kuri
- `skills/custom/` è riservata alle tue skill specifiche di progetto
- `skills/custom/hackernews-page-2.md` è un esempio concreto di skill personalizzata
- `.claude/skills/kuri-server/SKILL.md` rimane sincronizzata per le skill di repo in stile Claude
La skill di base ora spiega anche quale percorso browser usare:
- `kuri` HTTP API: automazione Chrome/CDP di produzione con sessioni, snapshot, azioni, HAR, cookie e screenshot
- `kuri-fetch`: estrazione fetch/testo standalone senza Chrome
- `kuri-browse`: navigazione interattiva da terminale
- `kuri-agent`: automazione CLI scriptabile contro il server Kuri
- `kuri-browser/`: runtime browser nativo Zig separato e sperimentale per il lavoro di parità
Per la CLI del browser sperimentale:
```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
```
`kuri-browser serve-cdp` espone il rilevamento HTTP in stile Chrome più un router JSON-RPC WebSocket minimale per i test di fumo del protocollo. La valutazione a runtime restituisce oggetti remoti CDP in formato V8 supportati da QuickJS; questo non aggiunge una dipendenza da V8 e non è ancora una compatibilità completa con Playwright/Puppeteer.
Gli screenshot in `kuri-browser` attualmente delegano al renderer principale Kuri/CDP. Avvia prima `./zig-out/bin/kuri`, poi:
```bash
cd kuri-browser
zig build run -- screenshot https://example.com --out example.jpg --compress --kuri-base http://127.0.0.1:8080
```
`--compress` acquisisce una baseline PNG e un candidato JPEG, scrive il file più piccolo e riporta il risparmio in byte. Misurazione locale attuale su `https://example.com`: da `20,523` byte PNG a `18,183` byte JPEG qualità 50, con un risparmio di `2,340` byte ovvero `11%`.
### Avanzate
| Percorso | Descrizione |
|------|-------------|
| `GET /diff/snapshot` | Delta compatto `+`/`~`/`-` rispetto allo snapshot precedente (ciclo di azioni dell'agente) |
| `GET /emulate` | Emulazione dispositivo |
| `GET /geolocation` | Imposta geolocalizzazione |
| `POST /upload` | Caricamento file |
| `GET /script/inject` | Inietta JavaScript |
| `GET /intercept/start` | Avvia l'intercettazione delle richieste |
| `GET /intercept/stop` | Ferma l'intercettazione |
| `GET /screenshot/annotated` | Screenshot con annotazioni degli elementi |
| `GET /screenshot/diff` | Diff visivo tra screenshot |
| `GET /screencast/start` | Avvia screencast |
| `GET /screencast/stop` | Ferma screencast |
| `GET /video/start` | Avvia registrazione video |
| `GET /video/stop` | Ferma registrazione video |
| `GET /console` | Ottieni i messaggi della console |
| `GET /stop` | Ferma il caricamento della pagina |
| `GET /get` | Fetch HTTP diretto (lato server) |
| `GET /scrollintoview` | Scorri un elemento referenziato nella vista |
| `GET /drag` | Trascina da un ref a un altro |
| `GET /keyboard/type` | Digita testo con eventi tastiera |
| `GET /keyboard/inserttext` | Inserisci testo direttamente |
| `GET /keydown` | Invia un evento keydown |
| `GET /keyup` | Invia un evento keyup |
| `GET /wait` | Attendi lo stato ready o condizioni dell'elemento |
| `GET /tab/close` | Chiudi una scheda |
| `GET /highlight` | Evidenzia un elemento tramite ref o selettore |
| `GET /errors` | Ottieni errori di pagina/runtime |
| `GET /set/offline` | Attiva/disattiva l'emulazione di rete offline |
| `GET /set/media` | Imposta le funzionalità multimediali emulate |
| `GET /set/credentials` | Imposta le credenziali di autenticazione HTTP basic |
| `GET /find` | Trova corrispondenze di testo nella pagina corrente |
| `GET /trace/start` | Avvia il tracing di Chrome |
| `GET /trace/stop` | Ferma il tracing e restituisci i dati di trace |
| `GET /profiler/start` | Avvia il profiler JS |
| `GET /profiler/stop` | Ferma il profiler JS |
| `GET /inspect` | Ispeziona un elemento o lo stato della pagina |
| `GET /set/viewport` | Imposta la dimensione del viewport |
| `GET /set/useragent` | Sovrascrivi lo user agent |
| `GET /dom/attributes` | Ottieni gli attributi dell'elemento |
| `GET /frames` | Elenca l'albero dei frame |
| `GET /network` | Ispeziona lo stato/le richieste di rete |
---
## 🛡️ Stealth & Bot Evasion
Kuri applica automaticamente le patch anti-rilevamento all'avvio — nessuna configurazione manuale necessaria.
### Cosa viene applicato
- **`Page.addScriptToEvaluateOnNewDocument`** — le patch stealth vengono eseguite prima di qualsiasi JS della pagina
- **navigator.webdriver = false** — nasconde il flag di automazione a livello Chromium (`--disable-blink-features=AutomationControlled`)
- **Spoofing WebGL/Canvas/AudioContext** — sconfigge il rilevamento basato su fingerprint
- **Rotazione UA** — 5 user agent realistici Chrome/Safari/Firefox
- **chrome.csi/chrome.loadTimes** — stub per i controlli specifici di Akamai
### Rilevamento blocchi bot
Navigate rileva automaticamente i blocchi e restituisce un fallback strutturato:
```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
```
Rileva: **Akamai**, **Cloudflare**, **PerimeterX**, **DataDome**, captcha generico.
### Supporto proxy
```bash
KURI_PROXY=socks5://user:pass@residential-proxy:1080 ./zig-out/bin/kuri
KURI_PROXY=http://proxy:8080 ./zig-out/bin/kuri
```
### Siti testati
| Sito | Protezione | Risultato |
|------|-----------|--------|
| Singapore Airlines | Akamai WAF | ✅ Aggirato (era bloccato prima della v0.4.0) |
| Shopee SG | Anti-frode personalizzato | ✅ La pagina si carica, reindirizza al login |
| Google Flights | Nessuna | ✅ Interazione completa |
| Booking.com | PerimeterX | ⚠️ Richiede proxy |
---
## 🔧 kuri-fetch
---
[Read more](https://github.com/justrach/kuri)