agent-browser

Browser Automation with agent-browser

Performance Rules (CRITICAL)

• ALWAYS chain commands with && when you don't need intermediate output. Each separate tool call costs seconds of round-trip latency.
• ALWAYS combine open + wait + snapshot into one call: agent-browser open <url> && agent-browser wait --load load && agent-browser snapshot -i
• ALWAYS batch multiple interactions (fill, click, select) into one && chain when refs are already known.
• Use --load load (DOM load event) by default. Only use networkidle when you specifically need all XHR/fetch to complete (e.g., waiting for API-driven content).
• Do NOT snapshot after every interaction — only re-snapshot when you need to discover new element refs (after navigation or major DOM changes).

Core Workflow

Every browser automation follows this pattern:

1. Navigate + Snapshot (one call): agent-browser open <url> && agent-browser wait --load load && agent-browser snapshot -i
2. Interact: Batch all interactions using known refs in one && chain
3. Re-snapshot: Only after navigation or major DOM changes

# Step 1: Open and discover elements (ONE tool call)
agent-browser open https://example.com/form && agent-browser wait --load load && agent-browser snapshot -i
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

# Step 2: Batch all interactions (ONE tool call)
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3 && agent-browser wait --load load

# Step 3: Only snapshot if you need to verify or discover new elements
agent-browser snapshot -i

This reduces 7+ round-trips to just 2-3.

Essential Commands

# Navigation
agent-browser open <url>              # Navigate (aliases: goto, navigate)
agent-browser close                   # Close browser

# Snapshot
agent-browser snapshot -i             # Interactive elements with refs (recommended)
agent-browser snapshot -i -C          # Include cursor-interactive elements
agent-browser snapshot -s "#selector" # Scope to CSS selector

# Interaction (use @refs from snapshot)
agent-browser click @e1               # Click element
agent-browser fill @e2 "text"         # Clear and type text
agent-browser type @e2 "text"         # Type without clearing
agent-browser select @e1 "option"     # Select dropdown option
agent-browser check @e1               # Check checkbox
agent-browser press Enter             # Press key
agent-browser scroll down 500         # Scroll page

# Get information
agent-browser get text @e1            # Get element text
agent-browser get url                 # Get current URL
agent-browser get title               # Get page title

# Wait
agent-browser wait @e1                # Wait for element
agent-browser wait --load load        # Wait for DOM load (fast, preferred)
agent-browser wait --load networkidle # Wait for network idle (slow, use only when needed)
agent-browser wait --url "**/page"    # Wait for URL pattern
agent-browser wait 2000               # Wait milliseconds

# Capture
agent-browser screenshot              # Screenshot to temp dir
agent-browser screenshot --full       # Full page screenshot
agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
agent-browser pdf output.pdf          # Save as PDF

# Diff (compare page states)
agent-browser diff snapshot                          # Compare current vs last snapshot
agent-browser diff screenshot --baseline before.png  # Visual pixel diff
agent-browser diff url <url1> <url2>                 # Compare two pages