Agent Browser

Browser Automation with agent-browser

Use agent-browser for browser tasks: navigate sites, fill forms, click controls, authenticate, capture screenshots/PDFs, extract page data, test web apps, compare page states, or automate repeatable browser interactions.

Required follow-up reads

Read references only when the task crosses the trigger below. Keep this file as the default path for routine open/snapshot/interact/capture work.

Entry Point

Canonical entry:

uv run --script <skill-dir>/scripts/cli.py ...

Set <skill-dir> to this skill directory. NEVER rely on shell functions, shell sourcing, executable bits, or shebang dispatch. The wrapper delegates to nix run github:numtide/llm-agents.nix#agent-browser -- ... and preserves exit codes.

Examples use agent-browser ... as readable shorthand for uv run --script <skill-dir>/scripts/cli.py ...; invoke the canonical command in actual tool calls unless the environment already provides an equivalent agent-browser executable.

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

Command Chaining

You MAY chain commands with && in one shell invocation. The browser persists between commands via a background daemon, so chaining is safe only when later commands need no unobserved intermediate output.

agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
agent-browser fill @e1 "user@example.com" && agent-browser fill @e2 "password123" && agent-browser click @e3
agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png

Use && only when intermediate output is irrelevant, such as open + wait + screenshot. Run commands separately when output determines the next action, especially snapshot -i before ref-based interaction.

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 (divs with onclick, cursor:pointer)
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

# 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

For downloads, tabs/windows, cookies/storage, network, dialogs, JavaScript, global options, debugging commands, and full flag lists, read references/commands.md.

Common Patterns

Read references/common-patterns.md when you need complete examples for:

• form submission;
• auth vault and state persistence;
• session persistence and parallel sessions;
• data extraction and JSON output;
• connecting to existing Chrome/CDP;
• color scheme, headed visual browser, local files;
• iOS Simulator/Mobile Safari workflows

Advanced Workflows

Read references/advanced.md only when you need content boundaries, allowlists, action policy, output limits, snapshot/screenshot diffing, timeout strategy, ref lifecycle troubleshooting, semantic locators, eval, or persistent config behavior.

Experimental: Native Mode

Native mode is experimental and not RECOMMENDED for production. Read references/native-mode.md before using --native or AGENT_BROWSER_NATIVE=1, and always run agent-browser close before switching between native and default mode within the same session.