Kuri 🌰

Installazione```sh

curl -fsSL https://kuri.trilok.ai/download | sh

macOS arm64/x86_64 e Linux x86_64/arm64. Singolo binario, nessuna dipendenza runtime.

Download diretti: [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)

---

**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 · Test di sicurezza · Controllo dispositivi iOS + Android

[Guida rapida](#-quick-start) · [Benchmark](#-benchmarks) · [kuri-agent](#-kuri-agent) · [Test di sicurezza](#-security-testing) · [API](#-http-api) · [Competenze](#-skills) · [Changelog](https://github.com/justrach/kuri/blob/main/CHANGELOG.md)

> **Perché i team passano a Kuri:** le build `ReleaseFast` attuali su 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`). Le differenze tra strumenti andrebbero ricalcolate nello stesso ambiente prima di citare una percentuale.

---

## Perché Kuri vince per gli agenti

La maggior parte degli strumenti browser è stata costruita per ingegneri QA. Kuri è costruito per i cicli degli agenti: leggi la pagina, mantieni basso il costo in token, agisci su riferimenti stabili e vai avanti.

- **135 endpoint HTTP** — parità completa con agent-browser e browser-use, dall'ispezione React alle Core Web Vitals.
- **7-12% di token in meno** rispetto ad agent-browser su pagine reali grazie al formato ref `@eN` e al rendering a prefisso zero.
- **Osservazioni 44x 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 un'unica chiamata HTTP, eliminando N-1 round-trip e N-1 passaggi LLM.
- **Compatibile con React** — eventi mouse CDP affidabili ed eventi tastiera per carattere attivano `onClick` e `onChange` di React 18/19.

### Token dello snapshot: Google Flights `SIN → TPE`

Nuova esecuzione il 2026-05-24 in questo workspace, misurata con `wc -c` e approssimazione `chars/4`.

| Tool / Modalità | Caratteri | ~Token | Nota |
|---|---:|---:|---|
| `kuri snap` (complete) | 8,499 | **2,124** | Tutti i nodi + ref interattivi |
| `kuri snap` (solo interattivi) | ~3,000 | **~750** | Ideale per i cicli degli agenti |
| `kuri /page/state` | 190 | **48** | Osservazione leggera (url, titolo, scroll%, conteggi) |
| snapshot agent-browser (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:
- ref `@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 del flusso di lavoro completo: `go → snap → click → snap → eval`

| Strumento | Token per ciclo |
|---|---:|
| **kuri-agent** | **~3,400** |
| Con `/page/state` al posto del secondo snap | **~1,700** |
| Con `POST /batch` (tutto in un'unica 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 per costo di token per passaggio. Misurato testa a testa il 2026-07-04 — stesso Chrome, stessa scheda, conteggi reali con `tiktoken` `o200k_base` (metodologia completa e riproduzione: **[benchmarks/libretto_comparison.md](https://github.com/justrach/kuri/blob/main/benchmarks/libretto_comparison.md)**). La ripartizione onesta:

| Aspetto | 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 | in parità | kuri di default 4,424 vs 813 — kuri emette tutti i 259 ref, libretto tronca di default. Con `limit=5` kuri genera 555 token (**1.46× sotto libretto**), 34 ref + marcatori `… +45 more` |
| Traiettoria (feed, 9 click) | **kuri**, di poco | 898 vs 939 token (base `limit=5` + loop di diff vs loop di exec) — parità-leggero vantaggio; la perdita 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 loop a ogni esecuzione |

**Cosa kuri ha imparato studiando libretto** (tutto incluso in questa release): un loop diff-first (`take_snapshot_diff`, ~38 token/passaggio); un diff adattivo che ripiega su uno snapshot completo con un'intestazione `! page replaced` alla navigazione; righe di rimozione con sola identità; screenshot scritti su disco (viene restituito il percorso, i byte non entrano mai nel contesto); `get_page_state` via MCP; e — dopo la riscrittura di `parseA11yNodes` come vera traversata DFS dell'albero — **troncamento opt-in delle liste** (`/snapshot?limit=N`, una riga `… +K more` per esecuzione limitata), **riacquisizione con scope** (`scope=@ref`) e **indentazione gerarchica**, il tutto esposto 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 ora costa **898** con base troncata + diff — 49× più economica, e sotto i 939 di libretto.

> Le tabelle precedenti usano un'approssimazione dei token `chars/4`; il confronto con libretto usa conteggi reali di `tiktoken`. Ricalcola i numeri tra strumenti nel tuo ambiente prima di citare una percentuale.

### Dimensioni del binario e memoria

Misurato su Apple M4 Pro, macOS 26.4.1. I binari attuali sono stati compilati con `-Doptimize=ReleaseFast`.

| Binario | Dimensioni attuali |
|---|---:|
| `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) |

### La RSS è rimasta stabile durante la migrazione a Zig 0.16

Misurata sulla build attuale `v0.4.3` `ReleaseFast` con `/usr/bin/time -l`.

| Comando | RSS massima media `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