Browser Tool

Browser Automation with agent-browser

The CLI uses Chrome/Chromium via CDP directly. Install via npm i -g agent-browser or brew install agent-browser.

Provided Tools

• browser - agent-browser CLI. Supports snapshot refs (@e1, @e2) for fast element selection. Use for JS-heavy sites, SPAs, login-required pages.
• browser_extension - Chrome extension-based browser control (uses real browser with logins). Preferred for authenticated access.

When to use browser (instead of web_fetch)

• JS-heavy sites (SPAs, React/Next.js/Astro apps that render client-side)
• Pages behind login or authentication
• Sites that need JavaScript to load content (pricing tables, dynamic data)
• When web_fetch returns mostly empty HTML with <script> tags

When to use web_fetch (instead of browser)

• Static pages, REST APIs, documentation with server-rendered content
• RSS feeds, JSON endpoints
• Simple HTML pages that don't need JavaScript

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 "user@example.com"
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.

agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i

When to chain: Use && when you don't need to read the output of an intermediate command. Run commands separately when you need to parse the output first (e.g., snapshot to discover refs, then interact).

Essential Commands

# Navigation
agent-browser open <url>              # Navigate
agent-browser close                   # Close browser
agent-browser close --all             # Close all active sessions

# Snapshot
agent-browser snapshot -i             # Interactive elements with refs (recommended)
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 networkidle # Wait for network idle
agent-browser wait --url "**/page"    # Wait for URL pattern
agent-browser wait 2000               # Wait milliseconds
agent-browser wait --text "Welcome"   # Wait for text to appear

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

# Downloads
agent-browser download @e1 ./file.pdf # Click to trigger download

# Network
agent-browser network requests        # Inspect tracked requests
agent-browser network requests --type xhr,fetch  # Filter by type

# Viewport
agent-browser set viewport 1920 1080  # Set viewport size
agent-browser set device "iPhone 14"  # Emulate device

Handling Authentication

Option 1: Import auth from user's browser (fastest)

agent-browser --auto-connect state save ./auth.json
agent-browser --state ./auth.json open https://app.example.com/dashboard

Option 2: Persistent profile (recurring tasks)

agent-browser --profile ~/.myapp open https://app.example.com/login
# ... login flow ... all future runs are authenticated

Option 3: Session name (auto-save/restore)

agent-browser --session-name myapp open https://app.example.com/login
# ... login flow ...
agent-browser close  # State auto-saved
# Next time: state auto-restored
agent-browser --session-name myapp open https://app.example.com/dashboard

Option 4: Auth vault (encrypted credentials)

echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp

Common Patterns

Form Submission

agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "jane@example.com"
agent-browser select @e3 "California"
agent-browser click @e5
agent-browser wait --load networkidle

Working with Iframes

Iframe content is automatically inlined in snapshots. Refs inside iframes carry frame context, so interact directly.

Data Extraction

agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5
agent-browser get text body > page.txt

Parallel Sessions

agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com
agent-browser session list

Visual Debugging

agent-browser --headed open https://example.com
agent-browser highlight @e1
agent-browser inspect  # Open Chrome DevTools

Ref Lifecycle (Important)

Refs (@e1, @e2, etc.) are invalidated when the page changes. Always re-snapshot after:

• Clicking links or buttons that navigate
• Form submissions
• Dynamic content loading (dropdowns, modals)

Diffing (Verifying Changes)

agent-browser snapshot -i          # Take baseline
agent-browser click @e2            # Perform action
agent-browser diff snapshot        # See what changed

Session Cleanup

Always close sessions when done to avoid leaked Chrome processes:

agent-browser close                # Close default session
agent-browser close --all          # Close all sessions

Security

• --content-boundaries wraps output in markers for LLM safety
• AGENT_BROWSER_ALLOWED_DOMAINS restricts navigation
• AGENT_BROWSER_MAX_OUTPUT prevents context flooding
• AGENT_BROWSER_ACTION_POLICY gates destructive actions

References

• references/commands.md -- Full command reference
• references/snapshot-refs.md -- Ref lifecycle
• references/session-management.md -- Parallel sessions
• references/authentication.md -- Login flows
• references/video-recording.md -- Recording
• references/profiling.md -- DevTools profiling
• references/proxy-support.md -- Proxy config

Templates

• templates/form-automation.sh -- Form filling
• templates/authenticated-session.sh -- Login + reuse state
• templates/capture-workflow.sh -- Content extraction