Drive a real browser from an AI agent with agent-browser
A snapshot-and-ref loop that lets an agent operate any web page one short shell command at a time.
TL;DR
agent-browser is a native Rust CLI. snapshot returns the page as compact text with a ref like @e1 per element; the agent acts on a ref, re-reads the page, and repeats.
Why this repo matters
Agents need a browser they can drive without writing Playwright scripts. The repo reduces the whole interaction to a loop of short shell calls, with the browser kept open between commands by a background daemon.
Best practices
- Read the page as an accessibility tree instead of raw HTML. It is compact and every actionable element gets a ref.
- Treat refs as a snapshot in time. After navigation or a DOM change, take a new snapshot before reusing them.
- Verify after every action (
get url, another snapshot) instead of assuming success. - Fail loudly: a click fails when the target is hidden, disabled, off-screen or covered, for example by a consent banner.
- Ship agent instructions with the tool. The CLI serves skills that match its installed version via
agent-browser skills get core.
How-to
Where do I start?
1. Install the CLI
npm install -g agent-browser
agent-browser install # downloads Chrome for Testing, first time only
No install needed for a trial: npx agent-browser open example.com.
Try it
Open a site you use, run snapshot -i, pick one ref, click it, and check get url. Then close with agent-browser close.
Pitfalls
- Reusing a ref after the page changed.
- Forgetting that each
--sessionhas its own daemon and browser; headless daemons exit after one hour without commands. - Letting a consent banner block clicks and not noticing the failure message.
Next steps
Try --cdp to attach to a Chrome you already run, or read the repo's quick start.