README

agent-browser

Browser automation for AI agents: open pages, read them as an accessibility tree, and act on elements from the shell.


  
  
  
  
  


agent-browser is a native Rust CLI that gives an AI agent a browser it can drive one command at a time. snapshot returns the page as compact text with a ref such as @e1 for each element. The agent acts on a ref, reads the page again to check the result, and repeats. The browser stays open between commands, so each step is one short shell call.

 Install

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


- Homebrew: brew install agent-browser, then agent-browser install.
- Linux: agent-browser install --with-deps also installs the browser's system libraries.
- No install: npx agent-browser open example.com.

Project installs, building from source, upgrade, and doctor are covered in Installation.

 Quick start

bash
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 snapshot for example.com:


- link "Learn more" [ref=e1]


- Refs describe the page at the time of the snapshot. After navigation or a DOM change, take a new snapshot before using refs again.
- CSS selectors, text, XPath, and semantic locators also work, for example agent-browser find role button click --name "Submit". See Selectors.
- A click fails, instead of reporting success, when the target is hidden, disabled, outside the viewport, or covered by another element such as a consent banner. Dismiss the covering element, take a new snapshot, and retry.

The full walkthrough is in the quick start.

 How it works

The CLI sends each command to a background daemon that starts on the first command and controls the browser over the Chrome DevTools Protocol. Each --session gets its own daemon and browser. By default, the daemon closes a headless browser and exits after one hour without commands, saving state first when session persistence is configured.

Chrome for Testing is the default browser. You can also attach to a running Chrome with --cdp or --auto-connect (CDP mode), select the Lightpanda or Obscura engine with --engine, drive Mobile Safari in the iOS Simulator, or use a cloud browser provider such as Browserbase, Browserless, Browser Use, Kernel, or AgentCore.

 For AI agents

The CLI ships skills that match its version:

bash
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


Install the discovery skill into an agent harness from skills.sh:

bash
npx

Top issues

Discussions

Latest release

New Features

- Added targeted skill references with skills get  --ref  and the MCP agent_browser_skills_get tool's refs argument, so agents can load one reference or template at a time (2310)
- Added Chrome security warnings when newer stable releases list CVE fixes, without blocking commands. Set AGENT_BROWSER_NO_VERSION_CHECK=1 to skip the check (2309)

 Bug Fixes

- Fixed session restarts when commands omit or change timeout settings, preserving open pages and reusing the running daemon's default timeout for waits (2288)
- Fixed bare open dropping configured profiles and browser arguments