agent-browser: a Rust CLI that drives Chrome through a daemon and element refs

One short shell call per step, because a daemon keeps the browser open

agent-browser is a native Rust CLI, and the process you type into is not the one holding the browser. The CLI sends each command to a background daemon that starts on the first command and controls the browser over the Chrome DevTools Protocol. Because the browser stays open between commands, an agent can issue one short call, read the output, and decide on the next call without paying for a browser launch each time.

The basic 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

The design choice here is that the agent never holds a browser handle. It holds only text: the snapshot output and the refs inside it. That keeps the tool usable from any harness that can run a shell command.

Refs such as @e1 describe the page only at snapshot time

A snapshot returns the page as compact text, and every element gets a ref. For example.com the entire snapshot is one line: link "Learn more" [ref=e1]. The agent then acts with `click @e1`.

The catch is that a ref is a description of the page at the moment of the snapshot, not a durable handle. After navigation or a DOM change, you have to take a new snapshot before using refs again. An agent that caches @e1 from an earlier step and clicks it after a route change is working from a stale map. The consequence for prompt design is concrete: every instruction to the agent should pair an action that changes the page with a fresh `snapshot`, which costs tokens on dynamic pages.

When refs are the wrong tool, other targeting works too: CSS selectors, text, XPath, and semantic locators, for example `agent-browser find role button click --name "Submit"`. Those are useful when you know the element in advance and do not want to snapshot first.

A click fails loudly when something covers the target

agent-browser does not report success for a click that did nothing. A click fails when the target is hidden, disabled, outside the viewport, or covered by another element such as a consent banner. That is a useful property for an agent loop, because a silent no-op would let the agent believe it had submitted a form.

The cost is that the agent must handle the failure itself. The recovery path is spelled out: dismiss the covering element, take a new snapshot, and retry. On sites with cookie banners, the first click on any page element can fail until the banner is gone, so a workflow that was written against a clean page will need an extra dismissal step. There is no automatic banner handling in what is described for the command, so that step belongs in your agent's instructions.

Installing the npm package does not install a browser

The npm package ships the native binary, and the browser is a second download:

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

Skipping the second command leaves you with a CLI and no Chrome for Testing, which is the default browser. Homebrew users run `brew install agent-browser` and then `agent-browser install`. On Linux, `agent-browser install --with-deps` also installs the browser's system libraries, so a bare Linux container is the case where the extra flag matters. To try it without installing anything, `npx agent-browser open example.com` works.

The repository's package.json declares engines node >=24.0.0 and pnpm >=11.0.0, with packageManager [email protected]. Those are the versions the repository itself is set up for, so check them before assuming an older Node will behave the same way when you install or build from source.

The daemon closes a headless browser after one hour without commands

By default, the daemon closes a headless browser and exits after one hour without commands. Each `--session` gets its own daemon and its own browser, so two agents using different session names do not share tabs, and each has its own idle clock.

What this means in practice: a long-running agent that pauses for more than an hour comes back to a browser that is gone. Any login or page state held only in that browser is lost, unless session persistence is configured, in which case the daemon saves state before it exits. If your workflow involves a human step in the middle, such as approving something for two hours, plan for persistence or plan to log in again. Nothing in the idle behaviour gives you a way to keep a headless browser alive indefinitely by default, so a monitoring-style use needs either regular commands or a persistence setup.

Chrome for Testing is only the default, and the other backends are chosen by flag

You can point the CLI at something other than the downloaded Chrome. `--cdp` or `--auto-connect` attach to a running Chrome. `--engine` selects the Lightpanda or Obscura engine. There is also a route to Mobile Safari in the iOS Simulator, and cloud browser providers: Browserbase, Browserless, Browser Use, Kernel, and AgentCore.

This list is a reason to treat agent-browser as a command surface rather than as one specific browser. The same `snapshot` and `click` vocabulary sits in front of all of them. The tradeoff is that each backend has its own page on agent-browser.dev, and the behaviour differences between engines are documented there rather than in the top-level overview. If your agent depends on a feature of Chrome, such as the `react` or `profiler` commands, confirm it on the engine you pick before committing to it.

The command groups are broad: navigation and reading, interaction, `wait`, capture (`screenshot`, `pdf`, `record`, `download`, `diff`), network and storage state, tabs, frames and dialogs, debugging, sessions and auth, and `stream` and `dashboard` for observing a run.

The installed skill is a stub that defers to the CLI version you have

For agents, the CLI carries its own instructions, versioned with the binary:

agent-browser skills get core                 # the core loop, refs, waiting, and common workflows
agent-browser skills get core --ref commands  # one reference, such as the full command list
agent-browser skills get core --full          # adds the full command reference and templates
agent-browser skills list                     # specialized skills: electron, slack, dogfood, and more

To add the discovery skill to an agent harness, run `npx skills add vercel-labs/agent-browser`. The installed skill is a thin stub that tells the agent to load `agent-browser skills get core`, so its instructions always match the installed CLI. The alternative is two lines in your AGENTS.md telling the agent to run that same command before first use.

For MCP clients, `agent-browser mcp` starts an MCP server over stdio. The benefit of the stub design is that upgrading the binary updates the agent's instructions with it. The cost is that the agent needs a shell to run `skills get core`, so the stub does nothing in an environment without one.

Six native targets, and a fast release pace on a 0.x version

Native binaries ship for macOS (ARM64 and x64), Linux (ARM64 and x64, glibc and musl), and Windows (x64). The npm package picks the right binary for the host. Windows is listed for x64 only, so a Windows ARM64 machine is outside the stated targets.

The project is not archived. Its last push was on 2026-11-01, and recent releases are v0.40.0 on 2026-10-27, v0.41.0 on 2026-10-29, and v0.41.1 on 2026-11-01. The license is Apache-2.0. Three tags in five days on a 0.x version is a reason to pin the version in your agent environment, particularly because the skill content is tied to the installed binary. A floating `npm install -g` on a build server can change the commands your agent is told to use between two runs.

Editorial conclusion

Use agent-browser if your agent can work in a loop of snapshot, act, snapshot, and you can tolerate re-reading the page after every navigation. Skip it if you need a persistent headless browser that never idles out, or if your platform is outside the six listed native targets. Before adopting it, check the Node requirement in package.json and decide whether to pin a version, since three releases landed in five days.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes