agent-browser

name	agent-browser
description	Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
allowed-tools	Bash(npx agent-browser:*), Bash(agent-browser:*)

Browser Automation with agent-browser

Core Workflow

Every browser automation follows this pattern:

1. Navigate: agent-browser open <url>
2. Snapshot: agent-browser snapshot -i (get element refs like @e1, @e2)
3. Interact: Use refs to click, fill, select
4. Re-snapshot: After navigation or DOM changes, get fresh refs

agent-browser open https://example.com/form
agent-browser snapshot -i
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

agent-browser fill @e1 "[e-mail]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i  # Check result

Command Chaining

Commands can be chained with && in a single shell invocation. The browser persists between commands via a background daemon.

# Chain open + wait + snapshot in one call
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

# Chain multiple interactions
agent-browser fill @e1 "[e-mail]" && agent-browser fill @e2 "password123" && agent-browser click @e3

Essential Commands

# Navigation
agent-browser open https://example.com
agent-browser go back
agent-browser reload

# Snapshots (Text/DOM)
agent-browser snapshot -i          # Include interactive refs (@e1)
agent-browser snapshot -i --all    # Include hidden/non-interactive

# Interaction
agent-browser click @e1
agent-browser fill @e2 "Text to type"
agent-browser select @e3 "Option Value"
agent-browser hover @e4
agent-browser press @e1 Enter
agent-browser scroll down

# Verification & Waiting
agent-browser diff snapshot        # Compare current state to last snapshot
agent-browser wait --load networkidle
agent-browser wait @e1             # Wait for element to appear
agent-browser wait 2000            # Wait 2000ms

# Cleanup
agent-browser close                # Close the background daemon session

Advanced Usage and Common Patterns

For information on Mobile Testing, Form Handling, iFrames, Shadow DOM, Security Configuration, Diffing, Timeouts, Ref Lifecycle, Annotated Screenshots (Vision), Locators, and JS evaluation:

See references/ADVANCED.md

Deep-Dive Documentation

Reference	When to Use
references/commands.md	Full command reference with all options
references/snapshot-refs.md	Ref lifecycle, invalidation rules, troubleshooting
references/session-management.md	Parallel sessions, state persistence, concurrent scraping
references/authentication.md	Login flows, OAuth, 2FA handling, state reuse
references/video-recording.md	Recording workflows for debugging and documentation
references/profiling.md	Chrome DevTools profiling for performance analysis
references/proxy-support.md	Proxy configuration, geo-testing, rotating proxies

Ready-to-Use Templates

Template	Description
templates/form-automation.sh	Form filling with validation
templates/authenticated-session.sh	Login once, reuse state
templates/capture-workflow.sh	Content extraction with screenshots

./templates/form-automation.sh https://example.com/form
./templates/authenticated-session.sh https://app.example.com/login
./templates/capture-workflow.sh https://example.com ./output