agent-browser: CLI browser automation for AI agents
/agent-browser
agent-browser is a Rust CLI that lets AI agents drive Chrome through short shell commands instead of a Playwright or Puppeteer script. Accessibility-tree snapshots with @e-style refs cut LLM prompt token cost, and batch mode skips per-command startup overhead. It's worth adopting once your agent already talks to the OS via shell commands; if your automation lives inside a Node process, the CLI round-trip is friction you don't need.
What is agent-browser?
agent-browser is a browser automation CLI built in Rust, designed for AI agents to control a Chrome session from the command line. Each command like open, snapshot, click @e2, or fill @e3 "text" talks to a background daemon over CDP, and snapshot returns an accessibility tree annotated with short refs so an agent can target elements without writing CSS selectors. Traditional selectors like #submit still work alongside the ref-based model.
Core capabilities: snapshots, refs, and batch execution
- ✓Accessibility-tree snapshots that assign short refs like @e2 to every interactive element, so an agent clicks by ref instead of guessing a CSS selector.
- ✓Batch execution runs a whole sequence of commands in one process, either as quoted arguments or as a piped JSON array, cutting the per-command startup cost of shelling out repeatedly.
- ✓Semantic find locators (find role, find text, find label, find testid, and more) for cases where a snapshot ref isn't what you want.
- ✓Network interception via network route, including request blocking, JSON response mocking, and HAR recording with configurable body capture.
- ✓Snapshot and screenshot diffing (diff snapshot, diff screenshot, diff url) to compare page state before and after an action or between two URLs.
- ✓A read command that fetches agent-readable text or markdown from a URL without launching Chrome at all, following llms.txt links when present.
- ✓Auto-handling of alert and beforeunload dialogs by default, with confirm/prompt still routed to explicit dialog accept/dialog dismiss calls.
- ✓Multi-tab and multi-window support with stable tab ids (t1, t2, ...) plus optional user-assigned labels that survive across tab switches.
Installing agent-browser
Install globally with `npm install -g agent-browser`, then run `agent-browser install` once to download Chrome from Chrome for Testing (Google's official automation channel) — existing Chrome, Brave, Playwright, and Puppeteer installs are detected automatically, so the daemon itself needs neither Playwright nor Node.js at runtime. If you want the version pinned in package.json, use `npm install agent-browser` instead of the global flag. macOS users can `brew install agent-browser`, and Rust users can `cargo install agent-browser` — both still need the one-time `agent-browser install` step. On Linux, run `agent-browser install --with-deps` to pull in system browser libraries; the command exits nonzero if the package manager can't install every one of them. Building from source needs Node.js 24+, pnpm 11+, and Rust: `pnpm install`, `pnpm build`, `pnpm build:native`, then `pnpm link --global`. `agent-browser upgrade` detects which install method you used and runs the matching update command.
Running your first browser automation workflow
A typical session is `agent-browser open example.com` to launch and navigate, `agent-browser snapshot` to get the accessibility tree with refs, then `agent-browser click @e2` or `agent-browser fill @e3 "[email protected]"` to act on a specific ref, followed by `agent-browser screenshot page.png` and `agent-browser close`. Clicks fail early if another element — a consent banner or modal, for example — covers the target's click point; deal with the covering element and take a fresh snapshot before retrying. One call, many steps. For multi-step flows, `agent-browser batch "open https://example.com" "snapshot -i" "screenshot"` runs everything in one process, or pipe a JSON array of commands via stdin with `--json`, adding `--bail` to stop on the first error. Screenshots hide native scrollbars by default for consistent output; pass `--hide-scrollbars false` if you need them visible.
Strengths
- ✓Accessibility-tree snapshots with element refs (@e2) replace brittle CSS-selector guessing, and traditional selectors still work as a fallback when you already know one.
- ✓Batch execution and a stdin JSON mode cut the process-startup overhead of running many small commands back to back, useful for scripted CI flows.
- ✓The daemon detects an existing Chrome, Brave, Playwright, or Puppeteer install automatically instead of forcing a second browser download in every case.
- ✓Deep debugging surface out of the box — HAR recording, snapshot/screenshot/URL diffing, a profiler, and console/error capture — without wiring in separate tooling.
- ✓`agent-browser upgrade` detects whichever install method you used (npm, Homebrew, Cargo) and runs the matching update command automatically.
Constraints and things to watch for
- △Chrome is downloaded through Chrome for Testing on the first `agent-browser install` run, an extra setup step beyond a plain `npm install` that Playwright/Puppeteer don't require in the same way.
- △The ref-based model (@e2, @e3) depends on taking a fresh snapshot before every action that follows a DOM change; stale refs after navigation or a covering-element block are a real failure mode the README calls out directly.
- △Linux setup needs system browser libraries via `agent-browser install --with-deps`, and the README states this command exits nonzero if the package manager can't install every one of them.
- △It's a CLI you shell out to, not a language-native library — a Node or Python agent that wants an in-process browser API, as Playwright and Puppeteer provide, has to manage a subprocess instead of just importing a package.
How agent-browser compares to Playwright and Puppeteer
Frequently asked questions
agent-browser is released under the Apache-2.0 license and published as open source on GitHub at vercel-labs/agent-browser, so it's free to install and use via npm, Homebrew, or Cargo. There's no separate paid tier or subscription mentioned anywhere in the project.
Running agent-browser day to day just needs Chrome, which the `agent-browser install` command downloads automatically from Chrome for Testing on first run, though an existing Chrome, Brave, Playwright, or Puppeteer install is detected too. Building agent-browser from source instead requires Node.js 24+, pnpm 11+, and Rust.
agent-browser is a standalone CLI binary, not a Rust library you import, so it's called the same way from Python, JavaScript, Ruby, or a shell script — via subprocess calls or piped batch commands — with no Rust code required on the caller's side.
agent-browser saves and restores login sessions with `state save` and `state load`, and lists or cleans old state files with `state list` and `state clean --older-than`. Cookies alone can be imported via `cookies set --curl`, which auto-detects a Copy-as-cURL dump, a JSON array, or a raw Cookie header.
agent-browser's `snapshot` command returns the page's accessibility tree with short refs like @e2 assigned to each element, so a follow-up `click @e2` targets exactly what was captured. Traditional CSS selectors such as #submit still work in agent-browser, but they depend on markup staying stable, while refs come from a fresh accessibility read each time.
agent-browser can intercept requests with `network route`, block them outright with `--abort`, or mock a response body with `--body`, including scoping by resource type such as blocking only scripts. It can also record a full HAR file via `network har start` and `network har stop`.
The problem it solves
AI agent frameworks that want browser control usually end up gluing together a language-specific library (Playwright, Puppeteer) plus their own logic for turning a live DOM into something an LLM can reason about — a step that ordinarily means dumping full HTML into the prompt and eating the token cost, or writing CSS-selector heuristics that break the moment a page's markup shifts. agent-browser folds both problems into one CLI: snapshot returns an accessibility tree with short element refs instead of raw HTML, and the refs stay stable across a session instead of depending on selectors tied to one DOM shape.
Best use cases
- •Scripting a login-and-scrape flow for a site with no public API, using state save/state load to reuse cookies across runs.
- •Feeding an LLM agent a compact accessibility snapshot instead of raw HTML so it can decide the next click with fewer tokens.
- •Running a batch of navigation/click/screenshot steps as one CLI call inside a CI job or cron script.
- •Mocking network responses with network route --body to test a frontend against fixture data without a real backend.
- •Recording a HAR file of a page load to debug what an app is actually requesting.
Who should try it — and who should skip
Reach for agent-browser if you're wiring an AI agent's tool layer to the OS shell — LangChain-style tool calls, a custom agent loop, or anything that already expects to invoke a binary and parse its output — and you want Chrome control without dragging in a Node or Python browser dependency. It's a poor fit if your automation is already a Playwright or Puppeteer test suite living inside a JS/TS codebase; rewriting working in-process test code around shell commands and refs buys you very little there.
Related repositories
Still deciding about agent-browser?
One click hands the question to an AI along with this page — see what it says about agent-browser.