Agent Browser Automation

1---2name: agent-browser-automation3description: Headless browser automation CLI for AI agents using native Rust binary with Chrome DevTools Protocol4triggers:5  - automate browser with agent-browser6  - use agent-browser for web scraping7  - browser automation CLI for AI8  - take screenshot with agent-browser9  - click and fill forms with agent-browser10  - agent-browser snapshot accessibility tree11  - batch browser commands with agent-browser12  - install agent-browser for automation13---14 15# agent-browser16 17> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.18 19`agent-browser` is a headless browser automation CLI built in Rust, designed for AI agents. It wraps Chrome via the Chrome DevTools Protocol (CDP) and exposes a fast, ergonomic command-line interface for navigation, interaction, accessibility snapshots, screenshots, network interception, and more — with no Node.js or Playwright runtime required.20 21## Installation22 23### Recommended (npm global)24```bash25npm install -g agent-browser26agent-browser install  # Download Chrome for Testing (first time only)27```28 29### macOS (Homebrew)30```bash31brew install agent-browser32agent-browser install33```34 35### Rust / Cargo36```bash37cargo install agent-browser38agent-browser install39```40 41### Local project dependency42```bash43npm install agent-browser44# Add to package.json scripts or invoke via npx45```46 47### Linux (with system dependencies)48```bash49agent-browser install --with-deps50```51 52## Quick Start53 54```bash55agent-browser open https://example.com56agent-browser snapshot                        # Accessibility tree with @refs (best for AI)57agent-browser click @e2                       # Click by ref from snapshot58agent-browser fill @e3 "hello@example.com"   # Fill by ref59agent-browser get text @e1                    # Get text content60agent-browser screenshot page.png61agent-browser close62```63 64## Core Commands65 66### Navigation67```bash68agent-browser open <url>           # Navigate (aliases: goto, navigate)69agent-browser get url              # Get current URL70agent-browser get title            # Get page title71agent-browser close                # Close browser (aliases: quit, exit)72```73 74### Accessibility Snapshot (recommended for AI agents)75```bash76agent-browser snapshot             # Returns accessibility tree with @ref IDs77agent-browser snapshot -i          # Interactive / compact mode78```79 80Snapshot output includes `@eN` refs you can use directly:81```82@e1 [button] "Submit"83@e2 [textbox] "Email" value=""84@e3 [link] "Sign in"85```86 87Then act on them:88```bash89agent-browser fill @e2 "user@example.com"90agent-browser click @e191```92 93### Interaction94```bash95agent-browser click <sel>                     # Click element96agent-browser dblclick <sel>                  # Double-click97agent-browser fill <sel> <text>               # Clear and fill input98agent-browser type <sel> <text>               # Type into element99agent-browser press <key>                     # Press key (Enter, Tab, Control+a)100agent-browser keyboard type <text>            # Type at current focus (real keystrokes)101agent-browser keyboard inserttext <text>      # Insert text without key events102agent-browser hover <sel>                     # Hover element103agent-browser select <sel> <value>            # Select dropdown option104agent-browser check <sel>                     # Check checkbox105agent-browser uncheck <sel>                   # Uncheck checkbox106agent-browser scroll down 500                 # Scroll (up/down/left/right, optional px)107agent-browser scroll down --selector "#feed"  # Scroll within element108agent-browser scrollintoview <sel>            # Scroll element into view109agent-browser drag <src> <target>             # Drag and drop110agent-browser upload <sel> /path/file.pdf     # Upload file111```112 113### Screenshots & PDF114```bash115agent-browser screenshot                          # Save to temp dir, print path116agent-browser screenshot page.png                 # Save to path117agent-browser screenshot --full page.png          # Full-page screenshot118agent-browser screenshot --annotate               # Numbered element labels overlay119agent-browser screenshot --screenshot-dir ./shots # Custom output directory120agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80121agent-browser pdf output.pdf                      # Save page as PDF122```123 124### Getting Element Info125```bash126agent-browser get text <sel>           # Text content127agent-browser get html <sel>           # innerHTML128agent-browser get value <sel>          # Input value129agent-browser get attr <sel> <attr>    # Attribute value130agent-browser get count <sel>          # Count matching elements131agent-browser get box <sel>            # Bounding box132agent-browser get styles <sel>         # Computed styles133agent-browser get cdp-url              # CDP WebSocket URL134```135 136### State Checks137```bash138agent-browser is visible <sel>139agent-browser is enabled <sel>140agent-browser is checked <sel>141```142 143### Semantic Locators (find)144```bash145agent-browser find role button click --name "Submit"146agent-browser find text "Sign In" click147agent-browser find label "Email" fill "test@example.com"148agent-browser find placeholder "Search..." fill "rust"149agent-browser find testid "login-btn" click150agent-browser find first ".item" click151agent-browser find nth 2 "a" text152agent-browser find role textbox fill "hello" --name "Username"153```154 155**Actions:** `click`, `fill`, `type`, `hover`, `focus`, `check`, `uncheck`, `text`156 157### Waiting158```bash159agent-browser wait "#modal"                          # Wait for element visible160agent-browser wait 2000                              # Wait N milliseconds161agent-browser wait --text "Welcome back"             # Wait for text162agent-browser wait --url "**/dashboard"              # Wait for URL pattern163agent-browser wait --load networkidle                # Wait for load state164agent-browser wait --fn "window.appReady === true"   # Wait for JS condition165agent-browser wait "#spinner" --state hidden         # Wait for element to disappear166```167 168**Load states:** `load`, `domcontentloaded`, `networkidle`169 170### JavaScript Eval171```bash172agent-browser eval "document.title"173agent-browser eval "JSON.stringify(window.__STATE__)"174agent-browser eval -b "BASE64_ENCODED_JS"175echo "return document.body.innerHTML" | agent-browser eval --stdin176```177 178### Batch Execution (efficient multi-step)179```bash180echo '[181  ["open", "https://example.com"],182  ["snapshot", "-i"],183  ["fill", "@e2", "user@example.com"],184  ["click", "@e1"],185  ["screenshot", "result.png"]186]' | agent-browser batch --json187 188# Stop on first failure189agent-browser batch --bail < commands.json190```191 192### Tabs & Frames193```bash194agent-browser tab                    # List tabs195agent-browser tab new https://...    # New tab with URL196agent-browser tab 2                  # Switch to tab 2197agent-browser tab close              # Close current tab198agent-browser frame "#my-iframe"     # Switch into iframe199agent-browser frame main             # Return to main frame200```201 202### Cookies & Storage203```bash204agent-browser cookies205agent-browser cookies set session_id "abc123"206agent-browser cookies clear207 208agent-browser storage local209agent-browser storage local set theme dark210agent-browser storage local clear211agent-browser storage session set cart '{"items":[]}'212```213 214### Network215```bash216agent-browser network route "**/api/users" --body '{"users":[]}'  # Mock response217agent-browser network route "**/ads/**" --abort                    # Block requests218agent-browser network unroute                                       # Remove all routes219agent-browser network requests --filter api                        # View requests220agent-browser network har start221agent-browser network har stop recording.har222```223 224### Browser Settings225```bash226agent-browser set viewport 1280 800227agent-browser set viewport 375 812 2        # With device pixel ratio (retina)228agent-browser set device "iPhone 14"229agent-browser set geo 37.7749 -122.4194230agent-browser set offline on231agent-browser set headers '{"X-Custom":"value"}'232agent-browser set credentials admin secret233agent-browser set media dark234```235 236### Auth State237```bash238agent-browser state save ./auth.json    # Save cookies + localStorage239agent-browser state load ./auth.json    # Restore auth state240agent-browser state list                # List saved states241agent-browser state show auth.json      # Summary of saved state242```243 244### Dialogs245```bash246agent-browser dialog accept             # Accept alert/confirm/prompt247agent-browser dialog accept "My input"  # Accept prompt with text248agent-browser dialog dismiss249```250 251### Clipboard252```bash253agent-browser clipboard read254agent-browser clipboard write "Hello, World!"255agent-browser clipboard copy           # Ctrl+C current selection256agent-browser clipboard paste          # Ctrl+V257```258 259### Diff & Visual Testing260```bash261agent-browser diff snapshot                                  # vs last snapshot262agent-browser diff snapshot --baseline before.txt            # vs saved file263agent-browser diff snapshot --selector "#main" --compact264agent-browser diff screenshot --baseline before.png265agent-browser diff screenshot --baseline b.png -o diff.png266agent-browser diff url https://v1.example.com https://v2.example.com267agent-browser diff url https://v1.example.com https://v2.example.com --screenshot268agent-browser diff url https://v1.example.com https://v2.example.com --selector "#content"269```270 271### Debug & Profiling272```bash273agent-browser trace start trace.zip274agent-browser trace stop275agent-browser profiler start276agent-browser profiler stop profile.json277agent-browser console                  # View console messages278agent-browser errors                   # View uncaught JS exceptions279agent-browser highlight "#button"      # Visually highlight element280agent-browser inspect                  # Open Chrome DevTools281agent-browser connect 9222             # Connect to existing browser via CDP port282```283 284## Common Patterns285 286### Login flow and save session287```bash288#!/bin/bash289agent-browser open https://app.example.com/login290agent-browser fill "#email" "$LOGIN_EMAIL"291agent-browser fill "#password" "$LOGIN_PASSWORD"292agent-browser click "[type=submit]"293agent-browser wait --url "**/dashboard"294agent-browser state save ./session.json295```296 297### AI agent loop with snapshot-driven interaction298```bash299#!/bin/bash300agent-browser open https://app.example.com301agent-browser state load ./session.json302 303# Get snapshot, parse @refs, act304SNAPSHOT=$(agent-browser snapshot)305echo "$SNAPSHOT"306 307# Agent determines @e5 is the search box308agent-browser fill @e5 "quarterly report"309agent-browser press Enter310agent-browser wait --load networkidle311agent-browser snapshot312agent-browser screenshot results.png313```314 315### Batch commands from a script (JSON)316```bash317cat > commands.json << 'EOF'318[319  ["open", "https://news.ycombinator.com"],320  ["wait", "--load", "networkidle"],321  ["get", "title"],322  ["snapshot"],323  ["screenshot", "hn.png"]324]325EOF326 327agent-browser batch --json < commands.json328```329 330### Scrape with mocked network331```bash332agent-browser open https://api-heavy-app.example.com333agent-browser network route "**/api/slow-endpoint" --body '{"data":"mocked"}'334agent-browser snapshot335agent-browser network unroute336```337 338### Full-page screenshot with annotations339```bash340agent-browser open https://example.com341agent-browser wait --load networkidle342agent-browser screenshot --full --annotate annotated.png343```344 345### Connect to already-running Chrome346```bash347# Start Chrome with remote debugging348google-chrome --remote-debugging-port=9222 &349 350agent-browser connect 9222351agent-browser open https://example.com352agent-browser snapshot353```354 355### Emulate mobile device356```bash357agent-browser set device "iPhone 14"358agent-browser open https://example.com359agent-browser screenshot mobile.png360```361 362### HAR recording for network analysis363```bash364agent-browser open https://example.com365agent-browser network har start366agent-browser click "#load-data"367agent-browser wait --load networkidle368agent-browser network har stop session.har369```370 371## Selector Reference372 373| Format | Example | Notes |374|--------|---------|-------|375| `@ref` | `@e1`, `@e12` | From `snapshot` output — preferred for AI |376| CSS | `#id`, `.class`, `[attr=val]` | Standard CSS selectors |377| Text | `"Sign In"` | Exact text match |378| XPath | `//button[@type='submit']` | Full XPath |379 380## Troubleshooting381 382### Chrome not found383```bash384agent-browser install              # Downloads Chrome for Testing385agent-browser install --with-deps  # Linux: also installs system libs386```387 388### Element not found / timing issues389```bash390agent-browser wait "#my-element"              # Wait for visibility first391agent-browser wait --load networkidle         # Wait for page to settle392agent-browser wait --fn "!!document.querySelector('#app')"393```394 395### Selector issues — use snapshot refs instead396```bash397# Instead of fragile CSS:398agent-browser click ".btn.btn-primary.submit-form"399 400# Use snapshot refs:401agent-browser snapshot  # Find @e7 = [button] "Submit"402agent-browser click @e7403```404 405### Debug what's on the page406```bash407agent-browser screenshot debug.png        # Visual check408agent-browser snapshot                    # Accessibility tree409agent-browser console                     # JS console output410agent-browser errors                      # Uncaught exceptions411agent-browser eval "document.readyState"412```413 414### Auth issues between sessions415```bash416agent-browser state save ./auth.json   # After successful login417agent-browser state load ./auth.json   # At start of next session418```419 420### Handling alerts/dialogs421```bash422# Set up handler BEFORE the action that triggers dialog423agent-browser dialog accept424agent-browser click "#delete-button"425```426 427### Performance — use batch for multi-step workflows428```bash429# Slow: one process per command430agent-browser open https://example.com431agent-browser fill "#q" "search"432agent-browser click "#submit"433 434# Fast: single process, multiple commands435echo '[["open","https://example.com"],["fill","#q","search"],["click","#submit"]]' \436  | agent-browser batch --json437```