agent-browser · diff
git:20260723.74fa0a8 to git:20260826.c0ed7cf
26 added, 324 removed. Audit A to A.
---
name: agent-browser
description: Fast browser automation CLI for AI agents. **ALWAYS use instead of Playwright MCP tools** for web testing, screenshots, form filling, and UI verification. Use when user says "open in browser", "check the site", "take a screenshot", "fill the form", "test the UI", or any browser interaction. Also use as a fallback when a task requires visual browser interaction that CLIs and APIs cannot handle (e.g., OAuth flows, complex dashboards, visual verification).
---
# 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.
+ ## When to use this skill
- ## Session Hygiene (REQUIRED — prevents leaked browsers)
+ **Prefer programmatic tools first** (CLIs, APIs, MCP servers). Use `agent-browser` when the task needs a **visual browser** (OAuth login, dashboards, visual verification), no CLI/API alternative exists, or the user explicitly asks to "open"/"browse"/"check the site"/"take a screenshot".
- 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**:
+ **Do NOT use Playwright MCP tools.** Always use the `agent-browser` CLI instead.
- - **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.
+ ## The one rule: every session is named and closed
- ## Starting a Browser Session
+ `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, on an auto-refreshing page, keeps pegging a CPU core) until something closes it. On shared fleet/worker hosts a leaked browser starves the box (CTL-1500). So:
- **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).**
+ - **Every command carries `--headed --session <name>`** — a short, task-specific name (e.g. `ctl-1500-verify`, `gh-review`). Never the implicit `default` session: it collides across concurrent workers and is the hardest leak to attribute.
+ - **Close in the same turn you finish**: `agent-browser --session <name> close`. If you took a wrong turn, close before starting over — never leave a session open "in case".
+ - **Never write an open-loop without a guaranteed close** (e.g. `until agent-browser --session s open <url>; do sleep …; done`) — each failed `open` can spawn/adopt a browser and a loop that exits without closing strands them. If you must poll, `open` once, then `wait`/`reload`, and `close` in a trap/`finally`.
+ - **On a worker/CI host**, close immediately — the host reaper (orphan-sweep vector 5) is a backstop, not a substitute.
```bash
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:
- ```bash
- 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:
- ```bash
- agent-browser --headed --session my-task snapshot -i -c
- ```
- 5. Optionally save the authenticated state for reuse:
- ```bash
- 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:
-
- ```bash
- --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):
-
- ```bash
- AGENT_BROWSER_HEADED=1 # Enable headed mode
- AGENT_BROWSER_SESSION=<name> # Set session name
- AGENT_BROWSER_PROFILE=<path> # Set profile directory
- ```
-
- ## Quick Reference
-
- ```bash
- # 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
- ```bash
- 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
- ```bash
- 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)
- ```bash
- agent-browser snapshot # Full accessibility tree with refs
- agent-browser snapshot -i # Interactive elements only
- agent-browser snapshot -i -c # Interactive + compact (RECOMMENDED)
- agent-browser snapshot -C # Include cursor-interactive elements
- agent-browser snapshot -d <n> # Limit tree depth
- agent-browser snapshot -s "<css>" # Scope to CSS selector
- agent-browser snapshot --json # JSON output
- ```
-
- ### Screenshots
- ```bash
- agent-browser screenshot [path] # Viewport screenshot
- agent-browser screenshot -f # Full page screenshot
- agent-browser screenshot --annotate # With numbered element labels
- agent-browser pdf <path> # Save as PDF
- ```
-
- ### Information
- ```bash
- agent-browser get text <sel> # Get text content
- agent-browser get html <sel> # Get innerHTML
- agent-browser get value <sel> # Get input value
- agent-browser get attr <sel> <attr># Get attribute
- agent-browser get title # Get page title
- agent-browser get url # Get current URL
- agent-browser get count <sel> # Count matching elements
- agent-browser get box <sel> # Get bounding box
- agent-browser get styles <sel> # Get computed styles
- ```
-
- ### State Checks
- ```bash
- agent-browser is visible <sel> # Check visibility
- agent-browser is enabled <sel> # Check enabled state
- agent-browser is checked <sel> # Check checked state
- ```
-
- ### Wait
- ```bash
- agent-browser wait <selector> # Wait for element visibility
- agent-browser wait <ms> # Wait N milliseconds
- agent-browser wait --text "text" # Wait for text to appear
- agent-browser wait --url "pattern" # Wait for URL pattern
- agent-browser wait --load networkidle # Wait for network idle
- agent-browser wait --fn "condition" # Wait for JS condition
- agent-browser wait --download [path] # Wait for download
- ```
-
- ### State Management (Auth Persistence)
- ```bash
- agent-browser state save <path> # Save cookies/localStorage to file
- agent-browser state load <path> # Load state from file
- agent-browser state list # List saved states
- agent-browser state show <file> # Show state contents
- agent-browser state clear [name] # Clear a specific state
- agent-browser state clear --all # Clear all states
- ```
-
- ### Saved Auth Flows
- ```bash
- agent-browser auth save <name> # Save an auth flow definition
- agent-browser auth save <name> \
- --url <url> \
- --username <user> \
- --password <pass> \
- --username-selector <sel> \
- --password-selector <sel> \
- --submit-selector <sel> # Save with full config
- agent-browser auth login <name> # Re-run a saved login
- agent-browser auth list # List saved auth configs
- agent-browser auth show <name> # Show auth config
- agent-browser auth delete <name> # Delete auth config
- ```
-
- ### Cookies & Storage
- ```bash
- agent-browser cookies # List cookies
- agent-browser cookies set <n> <v> # Set cookie
- agent-browser cookies clear # Clear cookies
- agent-browser storage local # List localStorage
- agent-browser storage local <key> # Get localStorage value
- agent-browser storage local set <k> <v> # Set localStorage value
- agent-browser storage local clear # Clear localStorage
- agent-browser storage session # Same for sessionStorage
- ```
-
- ### Tabs
- ```bash
- agent-browser tab # List tabs
- agent-browser tab new [url] # Open new tab
- agent-browser tab <n> # Switch to tab n
- agent-browser tab close [n] # Close tab
- ```
-
- ### Frames
- ```bash
- agent-browser frame <sel> # Switch to iframe
- agent-browser frame main # Return to main frame
- ```
-
- ### JavaScript
- ```bash
- agent-browser eval '<expression>' # Run JavaScript
- agent-browser eval --stdin # Read JS from stdin
- ```
-
- ### Console & Errors
- ```bash
- agent-browser console # View console messages
- agent-browser console --clear # Clear console log
- agent-browser errors # View JS errors
- ```
-
- ### Dialogs
- ```bash
- agent-browser dialog accept [text] # Accept dialog
- agent-browser dialog dismiss # Dismiss dialog
- ```
-
- ### Settings
- ```bash
- agent-browser set viewport <w> <h> # Set viewport size
- agent-browser set device <name> # Device emulation (e.g., "iPhone 14")
- agent-browser set media [dark|light] # Color scheme
- agent-browser set geo <lat> <lng> # Set geolocation
- agent-browser set offline [on|off] # Toggle offline mode
- agent-browser set headers <json> # Set global headers
- agent-browser set credentials <u> <p> # Set HTTP basic auth
+ agent-browser --headed --session my-task snapshot -i -c # interactive elements, compact
+ agent-browser --headed --session my-task click @e2
+ agent-browser --headed --session my-task fill @e3 "text"
+ agent-browser --headed --session my-task screenshot -f
+ agent-browser --headed --session my-task close
```
- ### Network
- ```bash
- agent-browser network requests # Show network requests
- agent-browser network requests --filter api # Filter requests
- agent-browser network requests --clear # Clear request log
- agent-browser network route <url> --abort # Block URL
- agent-browser network route <url> --body <json> # Mock response
- agent-browser network unroute [url] # Remove intercept
- ```
+ For a login flow: open the login page `--headed`, tell the user "A browser window opened — please log in, then let me know", wait for their confirmation, then continue with the same `--headed --session <name>`. Optionally persist it: `agent-browser --headed --session my-task state save ./auth-state.json`.
- ### Semantic Locators
- ```bash
- agent-browser find role <role> <action> # Find by ARIA role
- agent-browser find text <text> <action> # Find by text
- agent-browser find label <label> <action> # Find by label
- agent-browser find placeholder <ph> <action> # Find by placeholder
- agent-browser find alt <text> <action> # Find by alt text
- agent-browser find testid <id> <action> # Find by test ID
- agent-browser find nth <n> <sel> <action> # Find nth match
- ```
+ ## Reference
- ### Debug & Recording
- ```bash
- agent-browser trace start [path] # Start Playwright trace
- agent-browser trace stop [path] # Stop trace
- agent-browser record start <path> # Record interactions
- agent-browser record stop # Stop recording
- agent-browser highlight <sel> # Highlight element
- agent-browser connect <port|url> # Connect to existing browser
- ```
+ | topic | file |
+ | -- | -- |
+ | every global flag and env var | [`references/flags.md`](references/flags.md) |
+ | navigation, interaction, snapshot, screenshots, info, wait, semantic locators | [`references/commands.md`](references/commands.md) |
+ | state/auth, cookies/storage, tabs, frames, JS, console, dialogs, settings, network, debug | [`references/commands-advanced.md`](references/commands-advanced.md) |
- ## Important Rules
+ ## Efficiency tips
- 1. **Always use `--headed`** on every command — default is headless, user needs to see the browser
- 2. **Always use `--session <name>`** on every command — preserves state, enables recovery
- 3. **For authenticated sites**, use `--headed` and ask the user to log in manually
- 4. **Use snapshot -i -c** for AI-efficient page state
- 5. **Use @refs** from snapshots for interactions, not CSS selectors
- 6. **agent-browser, NOT Playwright MCP** — always prefer the CLI
- 7. **ALWAYS close when done** (REQUIRED): `agent-browser --session <name> close`. The daemon + browser outlive the CLI and leak a CPU-pegging browser on shared hosts if left open (CTL-1500). Never leave a session open; never use unnamed/shared-`default` sessions or abandoned `until … open` loops. See **Session Hygiene** above.
+ 1. Use `-i -c` on `snapshot` for interactive elements only, in compact form.
+ 2. Chain commands with `&&`.
+ 3. Use `@refs` from a snapshot directly — no CSS selectors needed.
+ 4. Sessions persist state across commands, so you don't need to re-authenticate per command.