eliasoulkadi agent-browser
Fast browser automation CLI for AI agents. Chrome/Chromium via CDP with
accessibility-tree snapshots and compact @eN element refs.
Install: npm i -g agent-browser && agent-browser install
Workflow
Step 1: Navigate to a page
agent-browser goto "https://example.com"
agent-browser wait @e3 # wait for element to appear
agent-browser html # get current DOM snapshot
The goto command navigates to a URL and waits for the page to load. Use wait to ensure specific elements are present before interacting. Always snapshot with html after navigation to get fresh @eN refs.
Step 2: Interact with elements
agent-browser click @e5 # click element by accessibility ref
agent-browser type @e7 "hello world" # type into input
agent-browser select @e9 "option-value" # select dropdown option
agent-browser check @e12 # toggle checkbox/radio
agent-browser hover @e15 # hover over element
agent-browser press Enter # press keyboard key
agent-browser scroll down 500 # scroll page by pixels
agent-browser drag @e5 @e20 # drag element to target
agent-browser upload @e8 "C:\path\to\file.pdf" # file input upload
All interactions use accessibility-tree element references (@eN). These are stable within a single page snapshot but invalidate after navigation or DOM mutations.
Step 3: Extract data or capture evidence
agent-browser screenshot page.png # full-page screenshot
agent-browser screenshot --element @e5 el.png # element screenshot
agent-browser screenshot --full-page false vp.png # viewport-only screenshot
agent-browser text # visible text content
agent-browser html # full HTML source
agent-browser pdf output.pdf # generate PDF
agent-browser console # browser console logs
agent-browser network # network request log
agent-browser eval "document.querySelector('.price').innerText" # run JS
agent-browser performance # Core Web Vitals metrics
agent-browser accessibility # accessibility tree dump
Step 4: Fill and submit forms
agent-browser goto "https://example.com/login"
agent-browser type @e3 "user@example.com" # email field
agent-browser type @e5 "password123" # password field
agent-browser click @e7 # submit button
agent-browser wait @e10 # wait for post-login element
agent-browser screenshot logged-in.png # verify success
For complex multi-step forms, screenshot after each step for debugging. Use agent-browser html between steps to get updated element refs if the DOM changes.
Step 5: Handle authentication
agent-browser vault set example.com "user:pass" # store encrypted credentials
agent-browser vault get example.com # retrieve credentials
agent-browser auth login "https://example.com" # automated OAuth/login flow
agent-browser session save mysession # save cookies + localStorage
agent-browser session load mysession # restore session state
agent-browser session list # list saved sessions
Credentials are encrypted at rest. Sessions persist cookies, localStorage, and IndexedDB across runs. Use sessions to skip repeated login flows.
Step 6: Verify and debug
agent-browser console --errors # only error-level logs
agent-browser console --since 30s # recent console output
agent-browser network --status 4xx,5xx # failed requests
agent-browser network --host api.example.com # filter by host
agent-browser cookies # inspect cookies
agent-browser eval "document.title" # run JS in page context
agent-browser performance # Core Web Vitals metrics
Common Workflow Patterns
Navigate and interact
agent-browser goto <url>
agent-browser click @e<ref> # click element by accessibility ref
agent-browser type @e<ref> "text" # type into element
agent-browser select @e<ref> "option" # select from dropdown
Extract data
agent-browser screenshot <path> # full page screenshot
agent-browser html # get current page HTML
agent-browser text # get visible text content
agent-browser pdf <path> # generate PDF
Browser state
agent-browser console # get browser console logs
agent-browser network # get network requests
agent-browser cookies # get/set cookies
agent-browser session save <name> # save session state
agent-browser session load <name> # restore session
Authentication
agent-browser vault set <site> <creds> # store encrypted credentials
agent-browser vault get <site> # retrieve and auto-fill
agent-browser auth login <url> # automated login flow
Load specialized workflows
agent-browser skills get core # base workflow (always load first)
agent-browser skills get core --full # full command reference
agent-browser skills get electron # Electron desktop apps (VS Code, Slack, Discord, Figma)
agent-browser skills get slack # Slack workspace automation
agent-browser skills get dogfood # Exploratory testing / QA / bug hunts
agent-browser skills get vercel-sandbox # Inside Vercel Sandbox microVMs
agent-browser skills get agentcore # AWS Bedrock AgentCore cloud browsers
agent-browser skills list # all available workflows
Error Handling
| Error | Cause | Fix |
|---|---|---|
Element @eN not found |
Element removed from DOM or re-rendered | Re-run agent-browser html to get fresh refs and retry |
Element @eN not interactable |
Element hidden, covered, or disabled | Use agent-browser html to check visibility; scroll into view first |
| Page load timeout | Network slow, infinite spinner, or redirect loop | Increase timeout with --timeout 30000; check agent-browser console for JS errors |
| Navigation failed | Invalid URL, DNS failure, or certificate error | Verify URL format; check network with agent-browser network |
| Authentication failed | Expired session, changed credentials, CAPTCHA | Re-login manually with agent-browser session save; update vault credentials |
| Browser not found | Chrome/Chromium not installed | Run agent-browser install to download compatible Chromium |
| Port already in use | Another instance of agent-browser running | Kill existing process or use --port <alt> to pick a different CDP port |
| Screenshot black/empty | Page not fully rendered or GPU issue | Wait for visible element first; try --full-page false for viewport only |
| Stale element reference | DOM mutated between snapshot and interaction | Always re-snapshot with agent-browser html before interacting |
| Rate limiting / bot detection | Site detects automation | Use agent-browser session load with real browser fingerprint; add delays between actions |
Anti-Patterns
| Pattern | Problem | Fix |
|---|---|---|
Hardcoding @eN refs across pages |
Refs change on every navigation | Always snapshot after navigation, never reuse stale refs |
| Clicking without waiting | Element may not be ready | Use agent-browser wait @eN before interacting |
| Blindly typing into any field | May type into wrong or readonly field | Verify element type from snapshot, use proper type/select/check |
| Ignoring console errors | Hidden JS failures break interactions | Always check agent-browser console --errors after issues |
| Forgetting to save session | Re-authentication needed on every run | agent-browser session save after manual login |
| Running without headless mode check | Visual inspection needed for debugging | Use --headless false when debugging; screenshot after each step |
| Bulk-extracting without rate limits | Triggering bot protection and IP bans | Add --delay 500 between actions; respect robots.txt |
| Using XPath or CSS selectors directly | Fragile, breaks on minor DOM changes | Prefer accessibility-tree @eN refs; fall back to text content matching |
Troubleshooting Quick Reference
| Issue | First Command to Run |
|---|---|
| Element not found | agent-browser html |
| Page not loading | agent-browser console |
| Auth failing | agent-browser session load <name> |
| Weird layout | agent-browser screenshot debug.png |
| Network errors | agent-browser network --status 4xx,5xx |
| Performance issues | agent-browser performance |
| Blank page after goto | agent-browser console --errors; agent-browser eval "document.readyState" |
| Click does nothing | agent-browser html (check element type, visibility, disabled state) |
Why agent-browser
- Fast native Rust CLI, not a Node.js wrapper
- Works with any AI agent (Cursor, Claude Code, Codex, Continue, Windsurf, etc.)
- Chrome/Chromium via CDP with no Playwright or Puppeteer dependency
- Accessibility-tree snapshots with element refs for reliable interaction
- Sessions, authentication vault, state persistence, video recording
Checklist
- Page loaded and rendered without errors before interacting
- Selectors use stable attributes (data-testid, aria-label) not dynamic classes
- Screenshots taken at each meaningful step for debugging
- Timeout set per-action (default 30s) to avoid indefinite hangs
- Browser context closed in finally block to prevent orphan processes
Sources
- Accessibility Tree specification (w3.org/TR/accname-1.2)
- agent-browser CLI (npm: agent-browser)
- Vercel Sandbox microVMs (vercel.com/docs/sandbox)
- AWS Bedrock AgentCore (docs.aws.amazon.com/bedrock)
- Electron CDP support (electronjs.org/docs/latest/api/debugger)