agent-browser

Generated source view for the actual executable engineering/agent-browser skill. The durable routing article is Browser Testing Skills. Source: skills/engineering/agent-browser/SKILL.md

Runtime Source

Bundled Resources

No bundled resource files.

Description

Default browser automation surface for Kevin's agents. Use when automating browsers, opening sites, scraping pages, filling forms, taking screenshots, testing UIs, extracting data, checking logged-in Chrome sessions, debugging localhost, validating frontend behavior, inspecting React/Web Vitals, or when the user asks for Playwright/Puppeteer-style browser interaction without explicitly requesting committed test files. Use Playwright only for regression tests or existing test suites.

Skill Source

---
name: agent-browser
description: Default browser automation surface for Kevin's agents. Use when automating browsers, opening sites, scraping pages, filling forms, taking screenshots, testing UIs, extracting data, checking logged-in Chrome sessions, debugging localhost, validating frontend behavior, inspecting React/Web Vitals, or when the user asks for Playwright/Puppeteer-style browser interaction without explicitly requesting committed test files. Use Playwright only for regression tests or existing test suites.
origin: personal
source_slug: agent-browser
---

# Browser Automation with agent-browser

CLI browser automation via Chrome/Chromium CDP. This is the default for agent-driven browser work: browsing, scraping, screenshots, form fills, logged-in Chrome flows, local UI QA, React/perf checks, and quick visual proof. Install: `npm i -g agent-browser`. Run `agent-browser install` to download Chrome.

## Routing Contract

- Use agent-browser first for interactive browser automation.
- Use a Chrome profile, `--auto-connect`, or state files for logged-in flows.
- Use Playwright only when creating or running committed regression tests, or when an existing repo test suite already owns the surface.
- Use Puppeteer only for legacy repos or vendor browser-rendering substrates that require it.
- Use browser-harness only for screenshot-first self-healing real-Chrome flows that agent-browser cannot handle.

## Core Workflow

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

```bash
agent-browser open https://example.com/form
agent-browser snapshot -i
agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait 2000
agent-browser snapshot -i
```

## Batch Execution

ALWAYS use `batch` for 2+ sequential commands:

```bash
agent-browser batch "open https://example.com" "snapshot -i"
agent-browser batch "click @e1" "wait 1000" "screenshot"
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"
```

Only run a single command when you need to read output before deciding the next step.

## Essential Commands

```bash
# Navigation
agent-browser open <url>
agent-browser close
agent-browser close --all

# Snapshot (get interactive element refs)
agent-browser snapshot -i
agent-browser snapshot -i --urls         # Include href URLs for links
agent-browser snapshot -s "#selector"    # Scope to CSS selector

# Interaction (use @refs from snapshot)
agent-browser click @e1
agent-browser fill @e2 "text"
agent-browser select @e1 "option"
agent-browser press Enter
agent-browser scroll down 500

# Get information
agent-browser get text @e1
agent-browser get url
agent-browser get title

# Wait
agent-browser wait @e1                  # Wait for element
agent-browser wait 2000                 # Wait milliseconds
agent-browser wait --text "Welcome"     # Wait for text
agent-browser wait --url "**/page"      # Wait for URL pattern

# Capture
agent-browser screenshot
agent-browser screenshot --full         # Full page
agent-browser screenshot --annotate     # With numbered element labels
agent-browser pdf output.pdf

# Diff (verify changes)
agent-browser diff snapshot             # Compare current vs last snapshot
agent-browser diff screenshot --baseline before.png

# Tab management
agent-browser tab list
agent-browser tab new https://example.com
agent-browser tab 2
agent-browser tab close

# Sessions
agent-browser --session site1 open https://site-a.com
agent-browser session list
```

## Authentication

```bash
# Auth vault (recommended)
echo "$PASSWORD" | agent-browser auth save github --url https://github.com/login --username user --password-stdin
agent-browser auth login github

# Session persistence (auto-save/restore)
agent-browser --session-name myapp open https://app.example.com/login

# State file
agent-browser state save ./auth.json
agent-browser state load ./auth.json

# Connect to existing Chrome
agent-browser --auto-connect open https://example.com
```

## Efficiency Patterns

- Use `--urls` with snapshot to get all href URLs upfront — visit directly instead of clicking and navigating back
- Snapshot once, act many times — never re-snapshot the same page
- Multi-page: get URLs in one snapshot, then batch each target site separately

## Ref Lifecycle

Refs (`@e1`, `@e2`) are invalidated when the page changes. Always re-snapshot after clicks that navigate, form submissions, or dynamic content loading.

## Security

```bash
# Content boundaries (recommended for AI agents)
export AGENT_BROWSER_CONTENT_BOUNDARIES=1

# Domain allowlist
export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"

# Output limits
export AGENT_BROWSER_MAX_OUTPUT=50000
```

## JavaScript Evaluation

```bash
# Simple expressions
agent-browser eval 'document.title'

# Complex JS: use --stdin with heredoc
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(Array.from(document.querySelectorAll("a")).map(a => a.href))
EVALEOF
```

## Related Skills

- `playwright` — committed regression tests and existing Playwright suites
- `seo-audit` — SEO auditing (uses browser for schema detection)
- `web-design-guidelines` — UI compliance checking

---

Timeline

• 2026-07-15 | Generated a browseable source page from the actual executable skill file. Source: skills/engineering/agent-browser/SKILL.md