agent-browser: a Rust CLI that gives AI agents a browser, now with a Chinese README

The first thing that trips people up with agent-browser is the ref lifecycle. You run snapshot -i, get a list of elements tagged @e1, @e2, and so on, click one, and then click another — and it fails. Not because the tool is broken, but because the page changed between snapshots and the refs you're holding describe a page state that no longer exists.

That detail is buried a few paragraphs into the English README. It's the kind of thing that costs a Chinese-speaking developer twenty minutes of confusion on a first run. Which is a decent argument for the project that prompted this article: a Chinese translation of the agent-browser documentation, published at yangshun2005/agent-browser-cn.

What the original project is

vercel-labs/agent-browser is a browser automation CLI aimed specifically at AI agents. It has 46,655 stars, is written in Rust, and is licensed Apache-2.0. The one-line description is "Browser automation CLI for AI agents."

The design premise is unusual enough to be worth stating plainly. Most browser automation libraries assume a script that runs start to finish. agent-browser assumes an agent that issues one command, looks at the result, decides what to do next, and issues another command. The browser stays open between those commands, so each step is a short shell invocation rather than a long-lived process.

The mechanism is a snapshot. Instead of returning a DOM tree or a screenshot, snapshot returns a compact text representation of the page with each element annotated with a ref like @e1. The agent acts on a ref, then reads the page again to confirm the action landed, then repeats.

A minimal loop looks like this:

agent-browser open example.com
agent-browser snapshot -i       # interactive elements, each with a ref
agent-browser click @e1         # act on a ref from that snapshot
agent-browser get url           # check the result
agent-browser close

For example.com, the snapshot is one line:

- link "Learn more" [ref=e1]

Under the hood, the CLI sends each command to a background daemon. That daemon starts on the first command and drives the browser over the Chrome DevTools Protocol. Each --session gets its own daemon and its own browser. By default the daemon shuts down the headless browser and exits after an hour with no commands.

Why a Chinese README matters here

This is not a translation of a tutorial or a blog post. It's a translation of the reference documentation for a tool whose failure modes are subtle and whose error messages are terse.

Consider the click behavior. The English README states that clicks fail rather than report success when the target is hidden, disabled, outside the viewport, or covered by another element such as a consent banner. That sentence is doing a lot of work. An agent that receives a false success will proceed down a wrong path and produce a confidently incorrect result. A developer who doesn't know this rule will spend time debugging the wrong layer.

The Chinese version handles this in two ways. The main body is a faithful translation of the original README, with a link to README_en.md for comparison. On top of that, the translator added a section labeled "中文快速上手" (Chinese quick start) that is explicitly marked as supplementary and not part of the original. That section front-loads the information a first-time user needs:

• What the project is and what problem it solves, in two paragraphs
• The shortest install-and-run path
• Environment requirements, including the node >=22.0.0 constraint from package.json and the current package version 0.41.2
• A "common pitfalls" list covering ref invalidation, failed clicks, the mandatory Chrome for Testing download, and daemon behavior

The environment section is a good example of the added value. The original README doesn't state a Node version requirement in prose — it's in the engines field of package.json. The Chinese version surfaces it. It also notes that installing the npm package and downloading Chrome for Testing may be slow from mainland China and suggests changing the npm registry or configuring download acceleration, while being honest that the original documentation provides no specific mirror configuration.

That last point is a small thing, but it's the kind of thing that determines whether someone gets to a working install or gives up.

Getting it running

The install path is the same regardless of which README you read:

npm install -g agent-browser
agent-browser install           # download Chrome for Testing (first time only)

On Linux, agent-browser install --with-deps also pulls in the browser's system libraries. Homebrew users can brew install agent-browser followed by agent-browser install. If you'd rather not install anything, npx agent-browser open example.com works.

Then the loop above. The -i flag on snapshot restricts output to interactive elements, which is usually what you want when driving a page rather than reading it.

Refs aren't the only option. CSS selectors, text, XPath, and semantic locators all work, for example:

agent-browser find role button click --name "Submit"

The ref model, and where it bites

The ref system is the core abstraction, and it's worth understanding its constraints before building anything on top of it.

A ref describes the page at the moment the snapshot was taken. Navigate, or let the DOM mutate, and every ref you hold is stale. The fix is always the same: take a new snapshot. There's no mechanism to update a ref in place.

The second constraint is that actions fail loudly rather than silently. This is the right design for agents — a false success is worse than an error — but it means your agent loop needs to handle failure as a normal case, not an exception. Close the obstructing element, re-snapshot, retry.

The third is the daemon. Commands go to a background process, not to a browser your script owns. Sessions are isolated: each --session has its own daemon and browser. If you're running multiple agents in parallel, that isolation is what keeps them from stepping on each other.

On the translation itself

The Chinese repository was published on 2026-11-08 and currently has zero stars. That's expected for a translation published today, and it's worth saying clearly: this is not a project with a community behind it yet. What it is, right now, is a readable Chinese rendering of a 46,655-star project's documentation, plus a short orientation section written for people who want to get to a running install without reading the whole thing.

The translator invites issues and PRs for inaccuracies, which is the right posture for a translation of technical documentation — the failure mode of a bad translation here isn't awkward prose, it's a subtly wrong description of behavior that sends someone down a wrong path.

If you read Chinese and you're evaluating agent-browser, the Chinese README will get you further faster than the English one, mostly because of the pitfalls section. If you read English comfortably, the original is the authoritative source and the translation adds convenience rather than information — with the exception of the environment requirements and the China-network note, which the original leaves implicit.

Either way, the underlying tool is the interesting part. A Rust CLI that hands an agent a persistent browser and a ref-based addressing scheme is a narrower, more verifiable interface than handing it a Playwright script. Whether that narrowness is a constraint or the whole point depends on what you're building.

---

Chinese documentation: https://github.com/yangshun2005/agent-browser-cn

I'm an independent enterprise AI delivery consultant — private LLM deployment, RAG, agent workflows, AIOps. If your team is stuck somewhere in that stack, my inbox is open.