| name | agent-browser |
| description | Headless browser automation CLI for AI agents. Use for web scraping, testing, form filling,
screenshots, and any browser interaction. Triggers: "browse", "open website", "click button",
"fill form", "screenshot", "scrape", "test login flow", "automate browser", "web automation".
|
agent-browser
CLI browser automation optimized for AI. Use refs from snapshots for reliable element selection.
93% less context than Playwright MCP, 95% first-try success rate.
Core Workflow
agent-browser open <url>
agent-browser snapshot -i
agent-browser click @e2
agent-browser fill @e3 "text"
agent-browser snapshot -i
agent-browser close
Snapshot (Most Important)
Get accessibility tree with element refs for deterministic selection:
agent-browser snapshot
agent-browser snapshot -i
agent-browser snapshot -c
agent-browser snapshot -d 3
agent-browser snapshot -i -c --json
Output example:
- heading "Example Domain" [ref=e1]
- button "Submit" [ref=e2]
- textbox "Email" [ref=e3]
Use refs with @ prefix: agent-browser click @e2
Essential Commands
Navigation
agent-browser open <url>
agent-browser back
agent-browser forward
agent-browser reload
Interaction
agent-browser click @ref
agent-browser fill @ref "text"
agent-browser type @ref "text"
agent-browser press Enter
agent-browser select @ref "value"
agent-browser check @ref
agent-browser hover @ref
agent-browser scroll down 500
Get Info
agent-browser get text @ref
agent-browser get value @ref
agent-browser get title
agent-browser get url
Check State
agent-browser is visible @ref
agent-browser is enabled @ref
agent-browser is checked @ref
Wait
agent-browser wait @ref
agent-browser wait 2000
agent-browser wait --text "Welcome"
agent-browser wait --load networkidle
Screenshot/Output
agent-browser screenshot
agent-browser screenshot page.png
agent-browser screenshot --full
agent-browser pdf output.pdf
Testing Patterns
Login Flow Test
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "test@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser snapshot -i
agent-browser get text @e1
Form Submission Test
agent-browser open https://app.example.com/contact
agent-browser snapshot -i
agent-browser fill @e1 "John Doe"
agent-browser fill @e2 "john@example.com"
agent-browser fill @e3 "Hello world"
agent-browser click @e4
agent-browser wait --text "Thank you"
agent-browser snapshot -i
Authentication State (Reuse Login)
agent-browser open https://app.example.com/login
agent-browser snapshot -i && agent-browser fill @e1 "user@test.com"
agent-browser fill @e2 "password" && agent-browser click @e3
agent-browser wait --load networkidle
agent-browser state save auth.json
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard
E2E Workflow Test
agent-browser open https://shop.example.com
agent-browser snapshot -i
agent-browser fill @e1 "laptop"
agent-browser click @e2
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser click @e5
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser click @e3
agent-browser wait --text "Added to cart"
agent-browser click @e4
agent-browser snapshot -i
agent-browser click @e2
agent-browser wait --url "**/checkout"
Visual Regression
agent-browser open https://app.example.com/component
agent-browser wait --load networkidle
agent-browser screenshot baseline.png --full
agent-browser screenshot current.png --full
Error State Testing
agent-browser open https://app.example.com/form
agent-browser snapshot -i
agent-browser click @e5
agent-browser wait 500
agent-browser snapshot -i
agent-browser get text @e1
Parallel Testing with Sessions
agent-browser --session test1 open https://app.example.com/feature-a
agent-browser --session test2 open https://app.example.com/feature-b
agent-browser --session test1 snapshot -i
agent-browser --session test2 snapshot -i
agent-browser session list
Debugging Tests
agent-browser open url --headed
agent-browser console
agent-browser errors
agent-browser highlight @e3
agent-browser trace start
agent-browser trace stop trace.zip
CSS/Text Selectors (Alternative)
When refs aren't available:
agent-browser click "#submit"
agent-browser click ".btn-primary"
agent-browser click "text=Sign In"
agent-browser find role button click --name "Submit"
Options
| Flag | Description |
|---|
--session <name> | Use isolated session |
--json | JSON output (for parsing) |
--headed | Show browser window |
--full | Full page screenshot |
Best Practices for Testing
- Always snapshot first - Get refs before interacting
- Use
wait after actions - Ensure page state settles
- Re-snapshot after navigation - Refs change between pages
- Use
--json for assertions - Parse structured output
- Save auth state - Avoid repeated login flows
- Use sessions for parallel tests - Isolated browser instances
- Use
--headed for debugging - See what's happening