The token-efficient browser for AI agents — one persistent, policy-guarded browser engineered so every observation costs the fewest tokens possible.
BetterWright is used in two ways — integrated, where your agent drives
the browser (skill, MCP, Pi, or the JS API), and
standalone, where BetterWright's own agent loop drives
(betterwright exec "<task>") and returns one JSON answer.
getting-started.md explains how to
pick; most pages apply to both.
Start here
New here: bun install -g betterwright && betterwright init. That one command
installs the browser, wires up the agent hosts on your machine, and proves the
whole path works by loading a real page.
| Page | What it covers |
|---|---|
| Getting started | init, the two usage shapes, first run, sessions, proof screenshots |
| Integration guide (SETUP.md) | Wiring BetterWright into any host — written to be followed by an AI agent |
| The built-in agent | betterwright exec, the interactive console, model adapters, runAgentTask() |
| JavaScript API | BetterWright, NetworkPolicy, the result envelope, vault API |
| SDK entrypoint | betterwright/sdk: the curated export list and the withBrowser helper |
| Browser API | Every sandboxed global inside a snippet: page, snapshot, screenshot, human, … |
| CAPTCHA recipes | Manual fallbacks for CAPTCHA interactions |
| Sessions & the daemon | Persistence, concurrency, interrupting a run, reconnecting |
Capabilities
| Page | What it covers |
|---|---|
| Credential vault | Encrypted storage, site matching, selector-free login, generated-password commits, and betterwright vault for reading your own saved passwords back |
| Cookie Sync | Copy selected local browser cookies into BetterChromium or an explicitly approved cloud browser |
| Live view & handoff | Watch/coach/take over in a browser tab; hosting presets, password gate, security model |
| CAPTCHA helpers | Local checkbox/Turnstile/slider/motion/drag-fit solving; numbered-crop vision loop for image grids |
| Network policy | What the browser may reach; the unliftable metadata floor |
| WebAgents batch workflows | Compact origin discovery and one-call dependency graphs with guarded first-party execution |
| Semantic action directories | Token-small control/evidence extraction and guarded batches for ordinary websites |
| WebMCP page tools | Typed capabilities published by the current page; discovery, safe invocation, and timeout cancellation |
| Skill packs | Per-site / per-password-manager packs, plus the host e2e-review playbook loaded only when a review is requested |
| Agent guidance | The operator prompt and its guardrail options |
Under the hood
| Page | What it covers |
|---|---|
| Architecture & security model | The worker process, the RPC loop, what is and isn't a security boundary |
| Launch identity | The coherent locale/timezone/geo identity layer; launch modes and egress matching |
| Browser providers | Managed fork, local executables, CDP endpoints, named cloud browsers, connected API keys, and betterwright boxes |
| Chromium fork | BetterWright's own Chromium build: farbling, discovery |
| Chromium fork patches | What each source patch in the pinned Chromium 151 build changes, and why |
| Headed / headless | Display modes over one persistent profile |