agent-browser

Files (6)

• SKILL.md
• evals.json · evals/
• trigger-eval.json · evals/
• advanced.md · references/
• commands.md · references/
• workflows.md · references/

SKILL.md (first lines)

# agent-browser

## Overview

**agent-browser** is an open-source browser automation CLI from Vercel Labs, built for LLM interaction with a **snapshot + refs** system: instead of a full DOM, `snapshot` returns an accessibility tree of just the interactive elements (buttons, inputs, links) with semantic labels, each tagged with a stable `@e1`-style ref. Full DOM dumps run 5000+ nodes / 200KB of context; an accessibility-tree snapshot is 50-100 elements / ~10KB, roughly a 93% reduction. Refs also survive re-renders, so they don't need re-deriving after every DOM tweak the way CSS selectors do.

See [When to Use vs Playwright](#when-to-use-vs-playwright) for when this CLI beats DOM-based tools.

### Installation

```bash
# macOS (preferred — managed by Homebrew)
brew install agent-browser

# Linux / fallback
npm install -g agent-browser

# Install browser binaries after either method
agent-browser install

# Linux: also install system dependencies
agent-browser install --with-deps

# Verify health
agent-browser doctor
```

## Quick Start

### Basic Workflow

```bash
# 1. Navigate to a page
agent-browser open https://example.com

# 2. Get snapshot with refs
agent-browser snapshot -i

# Output shows:
# textbox "Email" [ref=e1]
# textbox "Password" [ref=e2]
# button "Submit" [ref=e3]

# 3. Interact using refs
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3

# 4. Wait and verify
agent-browser wait --load networkidle
agent-browser snapshot -i
```

Refs are invalidated whenever the page changes (navigation, dropdown opening,
DOM re-render). Re-run `snapshot -i` after any action that could change the
page before reusing a ref: an ref from before the action may now point at a
different element or nothing at all.

### Session Management

Always pass `--session`: one named session per project prevents stale
daemons from accumulating across parallel agent sessions.

```bash
# Use project name as session (run this pattern everywhere)
agent-browser --session "$(basename "$PWD")" open https://app.com

# Authenticated flows: add persistent profile (gitignored)
agent-browser --session "$(basename "$PWD")" --profile .claude/browser-profile open https://app.com/login

# Stateless scraping/extraction: use Lightpanda instead (10x less memory)
agent-browser --session "$(basename "$PWD")" --engine lightpanda open https://public-site.com

# List all active sessions
agent-browser session list

# Diagnose + clean stale sockets (run when things feel wrong)
agent-browser doctor --fix

# Close this project's session only (never use --all with parallel projects)
agent-browser close --session "$(basename "$PWD")"
```

### Engine Choice

| Task | Engine | Why |
|---|---|---|
| Testing your own app, screenshots, React/SPA | `chrome` (default) | Full rendering, CDP, JS |
| Authenticated flows needing saved login | `chrome` + `--profile` | Persistent storage state |
| Bulk scraping / data extraction from public pages | `lightpanda` | 10x less memory, 10x faster |
| Paginated crawls, `get text` at scale | `lightpanda` | Ephemeral, no cache buildup |
| Extensions, headed mode, file access | `chrome` (required) | Lightpanda can't do these |

Rule: **if it only reads public pages and needs no login or screenshot → Lightpanda. Otherwise Chrome.**

## Command Cheat Sheet

```bash
agent-browser --session "$(basename "$PWD")" open <url>   # navigate
agent-browser snapshot -i                                  # get @refs
agent-browser click @e1                                    # click
agent-browser fill @e2 "text"                               # fill a field
agent-browser wait --load networkidle                       # wait for load
agent-browser get text @e3                                  # read element
agent-browser read <url> --outline                          # page as text, no browser
agent-browser is visible @e1                                 # verify state
agent-browser screenshot page.png                            # capture
agent-browser close --session "$(basename "$PWD")"          # cleanup
```

Full command surface (navigation, all interactions, `find` semantic
locators, waits, screenshots/video, tabs, network, cookies, auth, MCP server,
global flags) lives in [references/commands.md](references/commands.md).

## Reading Pages as Text: `read`

To get a page's content as agent-readable text, use `read` before reaching for a
browser session. It launches nothing when given a URL.

From mgiovani/cc-arsenal, MIT.

More from mgiovani/cc-arsenal