agent-browser CLI Reference

When to Use This Skill

Prefer programmatic tools first (CLIs, APIs, MCP servers). Use agent-browser when:

• The task requires a visual browser (OAuth login, dashboards, visual verification)
• No CLI/API alternative exists for the interaction
• The user explicitly asks to "open", "browse", "check the site", or "take a screenshot"
• You need to fill forms, click through UIs, or test web interfaces

Do NOT use Playwright MCP tools. If browser automation is needed, always use agent-browser CLI instead.

Session Hygiene (REQUIRED — prevents leaked browsers)

agent-browser runs a persistent per-session daemon that owns a real "Chrome for Testing" browser. That daemon outlives the CLI — the browser keeps running (and, if left on an auto-refreshing page, keeps re-rendering and pegging a CPU core) until something closes it. On shared fleet/worker hosts a leaked browser starves the box (CTL-1500). So treat every session as something you must open with a name and always close:

• REQUIRED: always pass --session <name>. Pick a short task-specific name (e.g. ctl-1500-verify, gh-review). Never rely on the implicit default session — a shared default collides across concurrent workers and is the hardest leak to attribute and clean up.
• REQUIRED: always close when done. End every task with agent-browser --session <name> close. Do it in the same turn you finish the browser work — do not leave a session open "in case". If you took a wrong turn, close before starting over.
• BANNED: unnamed / shared-default sessions. Every open must carry an explicit --session. An un-named session on a worker host is a leak waiting to happen.
• BANNED: abandoned open-loops. Never write retry/wait loops that call agent-browser ... open (e.g. until agent-browser --session s open <url>; do sleep …; done) without a guaranteed matching close. Each failed open can spawn/adopt a browser; a loop that exits without closing strands them. If you must poll, open once, then use wait/reload, and close in a trap/finally.
• On a worker/CI host, prefer the shortest-lived session possible and close it immediately; a phase worker that exits without closing relies on the host reaper (orphan-sweep vector 5) to clean up, which is a backstop, not a substitute.

Starting a Browser Session

ALWAYS use --headed and a named session. Headed mode shows a visible browser window so the user can watch. Sessions preserve browser state so they survive accidental closes and can be resumed. Always close the session when the task is done (see Session Hygiene above).

agent-browser --headed --session my-task open https://example.com
agent-browser --headed --session my-task snapshot -i -c

Pick a short descriptive session name for the task (e.g., v0-chat, gh-review, test-login). Use the same --headed --session <name> flags on every command.

Authentication Flow

If a site requires login, you MUST use --headed so the user can see and interact with the browser window.

1. Open the login page in headed mode with a named session:

   agent-browser --headed --session my-task open https://example.com/login
   

2. Tell the user: "A browser window opened. Please log in, then let me know when you're ready."
3. Wait for the user to confirm they've logged in. Do NOT proceed until they say so.
4. Then continue:

   agent-browser --headed --session my-task snapshot -i -c
   

5. Optionally save the authenticated state for reuse:

   agent-browser --headed --session my-task state save ./auth-state.json
   

Sessions persist across commands — once logged in, the session stays active for all subsequent commands. If the browser is closed accidentally, re-open with the same --session name to resume.

Global Flags

These flags apply to ALL commands and should appear before the command name:

--headed                    # Show visible browser window (default: headless) — ALWAYS USE THIS
--session <name>            # Use a named session (preserves state across commands) — ALWAYS USE THIS
--profile <path>            # Persistent browser profile directory (survives restarts)
--state <path>              # Load storage state from JSON file
--headers <json>            # Set HTTP headers scoped to origin
--proxy <url>               # Use a proxy server
--ignore-https-errors       # Ignore SSL certificate errors
--device <name>             # Emulate a device (e.g., "iPhone 14")
--json                      # Output in JSON format
--debug                     # Enable debug output
--config <path>             # Path to config file

Environment variables (alternative to flags):

AGENT_BROWSER_HEADED=1             # Enable headed mode
AGENT_BROWSER_SESSION=<name>       # Set session name
AGENT_BROWSER_PROFILE=<path>       # Set profile directory

Quick Reference

# Navigation (always include --headed --session <name>)
agent-browser --headed --session s open <url>    # Open URL
agent-browser --headed --session s back          # Navigate back
agent-browser --headed --session s reload        # Reload page

# Get page state (use -i -c for efficiency)
agent-browser --headed --session s snapshot -i -c  # Interactive elements only, compact

# Interact using @refs from snapshot
agent-browser --headed --session s click @e2       # Click element
agent-browser --headed --session s fill @e3 "text" # Fill input
agent-browser --headed --session s type @e3 "text" # Type (preserves existing)
agent-browser --headed --session s press Enter     # Press key

# Screenshots
agent-browser --headed --session s screenshot              # Viewport
agent-browser --headed --session s screenshot -f           # Full page
agent-browser --headed --session s screenshot file.png     # Save to file

# Get info
agent-browser --headed --session s get text @e1   # Get element text
agent-browser --headed --session s get url        # Current URL
agent-browser --headed --session s get title      # Page title

# Session management
agent-browser session list                         # List sessions
agent-browser --headed --session s close           # Close browser

Efficiency Tips

1. Use -i -c flags on snapshot to get only interactive elements in compact form
2. Chain commands with && for quick workflows
3. Use @refs directly from snapshots — no CSS selectors needed
4. Sessions persist — browser state maintained across commands
5. ALWAYS pass --headed — default is headless, user needs to see the browser

All Commands

Navigation

agent-browser open <url>           # Navigate (aliases: goto, navigate)
agent-browser back                 # Browser back
agent-browser forward              # Browser forward
agent-browser reload               # Reload page
agent-browser close                # Close browser session (aliases: quit, exit)

Interaction

agent-browser click <sel>          # Click element (--new-tab for new tab)
agent-browser dblclick <sel>       # Double-click
agent-browser focus <sel>          # Focus element
agent-browser type <sel> <text>    # Type without clearing
agent-browser fill <sel> <text>    # Clear then fill
agent-browser press <key>          # Press key (Enter, Tab, Control+a)
agent-browser hover <sel>          # Hover element
agent-browser select <sel> <val>   # Select dropdown option
agent-browser check <sel>          # Check checkbox
agent-browser uncheck <sel>        # Uncheck checkbox
agent-browser scroll <dir> [px]    # Scroll (up/down/left/right)
agent-browser scrollintoview <sel> # Scroll element into view
agent-browser drag <src> <tgt>     # Drag and drop
agent-browser upload <sel> <files> # Upload files

Snapshot (AI-Optimized)

agent-browser snapshot             # Full accessibility tree with refs
agent-browser s