Kuri 🌰

설치```sh

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

macOS arm64/x86_64 및 Linux x86_64/arm64. 단일 바이너리, 런타임 종속성 없음.

직접 다운로드: [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)

---

**AI 에이전트를 위한 브라우저 자동화 및 웹 크롤링. Zig로 작성. Node.js 제로.**

CDP 자동화 · A11y 스냅샷 · HAR 녹화 · 독립형 페처 · 인터랙티브 터미널 브라우저 · 에이전틱 CLI · 보안 테스트 · iOS + Android 기기 제어

[빠른 시작](#-quick-start) · [벤치마크](#-benchmarks) · [kuri-agent](#-kuri-agent) · [보안 테스트](#-security-testing) · [API](#-http-api) · [스킬](#-skills) · [Changelog](https://github.com/justrach/kuri/blob/main/CHANGELOG.md)

> **팀이 Kuri로 전환하는 이유:** 현재 Apple Silicon `ReleaseFast` 빌드는 바이너리당 2MB 미만을 유지하며, 2026-04-23에 새로 실행한 Google Flights 테스트에서 전체 `kuri-agent` 루프(`go→snap→click→snap→eval`)가 **3,392 토큰**으로 측정되었습니다. 퍼센트를 인용하기 전에 반드시 동일한 환경에서 크로스 툴 델타를 다시 실행하세요.

---

## Kuri가 에이전트에 유리한 이유

대부분의 브라우저 도구는 QA 엔지니어를 위해 만들어졌습니다. Kuri는 에이전트 루프를 위해 설계되었습니다: 페이지를 읽고, 토큰 비용을 낮게 유지하고, 안정적인 ref로 동작한 다음 다음 단계로 넘어갑니다.

- **HTTP 엔드포인트 135개** — React 검사부터 Core Web Vitals까지 agent-browser 및 browser-use와 완전한 동등성.
- 실제 페이지에서 `@eN` ref 형식과 zero-prefix 렌더링 덕분에 agent-browser보다 **토큰 7-12% 절감**.
- 동일한 Google Flights 페이지에서 전체 스냅샷(2,124 토큰) 대신 `/page/state`(48 토큰)로 **44배 더 가벼운 관측**.
- **배치 실행** — `POST /batch`는 단일 HTTP 호출로 N개 명령을 보내 N-1회 왕복과 N-1회 LLM 턴을 제거합니다.
- **React 호환** — 신뢰할 수 있는 CDP 마우스 이벤트와 문자별 키 이벤트가 React 18/19의 `onClick` 및 `onChange`를 발생시킵니다.

### 스냅샷 토큰: Google Flights `SIN → TPE`

이 워크스페이스에서 2026-05-24에 새로 실행했으며 `wc -c`와 `chars/4` 근사 방식으로 측정했습니다.

| 도구/모드 | 문자 수 | ~토큰 | 비고 |
|---|---:|---:|---|
| `kuri snap` (full) | 8,499 | **2,124** | 모든 노드 + 인터랙티브 ref |
| `kuri snap` (interactive only) | ~3,000 | **~750** | 에이전트 루프에 최적 |
| `kuri /page/state` | 190 | **48** | 경량 관측(url, 제목, 스크롤%, 개수) |
| agent-browser snap (추정) | ~9,183 | **~2,295** | `[ref=e0]` 형식 오버헤드 |

### 토큰 효율성: kuri vs agent-browser

| 페이지 | kuri 토큰 | agent-browser 토큰 | 절감 |
|---|---:|---:|---|
| example.com | 40 | 35 | -13% (단순 페이지, agent-browser는 루트 생략) |
| Hacker News | 386 | ~440 | **12% 절감** |
| Google Flights SIN→TPE | 2,124 | ~2,295 | **7% 절감** |

절감 효과는 kuri의 간결한 형식에서 비롯됩니다:
- `@e0` ref(3자) vs `[ref=e0]`(9자)
- 줄마다 `- ` 접두사 없음(2자 × 줄 수 절약)
- 동일한 들여쓰기, 동일한 노드 필터링

### 전체 워크플로 비용: `go → snap → click → snap → eval`

| 도구 | 주기당 토큰 |
|---|---:|
| **kuri-agent** | **~3,400** |
| 두 번째 snap 대신 `/page/state` 사용 시 | **~1,700** |
| `POST /batch` 사용 시(단일 호출로 모두 처리) | **~1,700** (동일한 토큰, 5회 대신 1회 HTTP 호출) |

### kuri vs libretto

[libretto](https://github.com/saffron-health/libretto)(Playwright + Node)는 단계별 토큰 비용에서 가장 근접한 경쟁자입니다. 2026-07-04에 동일한 Chrome, 동일한 탭에서 실측했으며 실제 `tiktoken` `o200k_base` 카운트를 사용했습니다(전체 방법론 및 재현: **[benchmarks/libretto_comparison.md](https://github.com/justrach/kuri/blob/main/benchmarks/libretto_comparison.md)**). 솔직한 비교 결과:

| 항목 | 승자 | 세부 정보 |
|---|---|---|
| 호출당 지연 시간 | **kuri** | 4–117 ms vs 1,344–1,500 ms(**13–376배 빠름** — 상주 서버 vs 명령마다 Node) |
| 스냅샷 토큰, 일반 페이지 | **kuri** | 단순 페이지 61 vs 151(2.5×), 기사 265 vs 363(1.37×) — 더 타이트한 문법 |
| 스냅샷 토큰, 대형 목록 | 분할 | kuri 기본 4,424 vs 813 — kuri는 259개 ref를 모두 출력하고 libretto는 기본적으로 잘라냅니다. `limit=5`를 사용하면 kuri는 555토큰을 렌더링하며(**libretto보다 1.46× 적음**), 34개 ref + `… +45 more` 마커를 표시 |
| 트라젝토리(feed, 클릭 9회) | **kuri**, 근소한 차이 | 898 vs 939 토큰(`limit=5` 베이스 + diff 루프 vs exec 루프) — 동등 수준에서 약간 우위; 앞선 5.1× 손실은 잘리지 않은 베이스 때문 |
| 반복 실행 | **libretto** | 트라젝토리를 Playwright 스크립트로 컴파일 → 0-토큰 재생; kuri는 실행마다 루프 비용을 다시 지불 |

**kuri가 libretto를 연구하여 얻은 것들**(이번 릴리스에 모두 포함): diff 우선 루프(`take_snapshot_diff`, 단계당 ~38 토큰); 내비게이션 시 `! page replaced` 헤더와 함께 전체 스냅샷으로 폴백하는 적응형 diff; 항목별 제거 라인; 스크린샷을 디스크에 저장(경로만 반환, 바이트는 컨텍스트에 들어가지 않음); MCP를 통한 `get_page_state`; 그리고 `parseA11yNodes`를 실제 DFS 트리 탐색으로 재작성한 후 — **옵트인 목록 잘라내기**(`/snapshot?limit=N`, 제한된 실행마다 `… +K more` 라인 1개), **범위 재캡처**(`scope=@ref`), **계층 들여쓰기**, MCP `take_snapshot`에서 `uid`/`limit`로도 노출됩니다. 순진한 전체 재스냅샷으로 44,285 토큰이 들던 9클릭 feed 트라젝토리는 잘린 베이스 + diff로 **898** 토큰이 들며 — 49배 저렴하고 libretto의 939보다 낮습니다.

> 위의 이전 표들은 `chars/4` 토큰 근사치를 사용합니다. libretto 비교는 실제 `tiktoken` 카운트를 사용합니다. 퍼센트를 인용하기 전에 자신의 환경에서 크로스 툴 수치를 다시 실행하세요.

### 바이너리 크기 및 메모리

Apple M4 Pro, macOS 26.4.1에서 측정했습니다. 현재 바이너리는 `-Doptimize=ReleaseFast`로 빌드되었습니다.

| 바이너리 | 현재 크기 |
|---|---:|
| `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) |

### Zig 0.16 마이그레이션 전반에 걸쳐 RSS 유지

현재 `v0.4.3` `ReleaseFast` 빌드를 `/usr/bin/time -l`로 측정했습니다.

| 명령어 | `v0.4.3` 평균 최대 RSS |
|---|---:|
| `kuri-fetch --version` | ~2.45 MiB |
| `kuri-browse --version` | ~2.45 MiB |
| `kuri-fetch --quiet --dump markdown http://example.com/` | ~9.17 MiB |

## 문제점

모든 브라우저 자동화 도구는 Playwright(~300 MB), Node.js 런타임, 그리고 npm 의존성의 연쇄를 끌어들입니다. AI 에이전트는 그저 페이지를 읽고, 버튼을 클릭하고, 다음으로 넘어가기를 원합니다.
**Kuri는 단일 Zig 바이너리입니다.** 네 가지 모드, 런타임 제로:```
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)

---

📦 설치

한 줄 설치 (macOS / Linux)```sh

curl -fsSL https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/install.sh | sh

플랫폼을 감지하여 올바른 바이너리를 다운로드하고 `~/.local/bin`에 설치합니다.
다운로드는 Kuri의 자체 관리 `release-channel` 브랜치에서 제공됩니다. macOS 바이너리는 Developer ID 인증서로 로컬 서명됩니다. GitHub Release 자산은 동일한 tarball을 미러링합니다.

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

설치 시 플랫폼에 맞는 네이티브 바이너리를 다운로드합니다.

릴리스 채널

Kuri의 안정 바이너리는 release-channel 브랜치에 있으며 GitHub raw URL에서 직접 제공됩니다.

• 안정 설치 관리자: https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/install.sh
• 안정 매니페스트: https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/latest.json
• 브랜치 보기: https://github.com/justrach/kuri/tree/release-channel/stable
• 직접 다운로드 패턴: https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/<version>/kuri-<version>-<target>.tar.gz

수동 설치

플랫폼에 맞는 tarball을 안정 릴리스 매니페스트 또는 GitHub 릴리스 페이지에서 다운로드하여 $PATH에 압축을 풉니다.

안정 설치 URL:```sh curl -fsSL https://raw.githubusercontent.com/justrach/kuri/release-channel/stable/install.sh | sh

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

### Platform support