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

These files are part of the executable skill folder and must be preserved with the skill source.

Description

Default browser automation and browser QA for Kevin's agents: open, scrape and test sites, fill forms, take screenshots, debug localhost, drive Electron or cloud browsers. Use for any browser task; use Playwright only for committed regression tests.

Skill Source

---
name: agent-browser
description: >-
  Default browser automation and browser QA for Kevin's agents: open, scrape and test sites, fill
  forms, take screenshots, debug localhost, drive Electron or cloud browsers. Use for any browser
  task; use Playwright only for committed regression tests.
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

<!-- folded-skills:auto:start -->
## Folded Skill References

These former standalone skills are bundled here as references to keep the runtime list compact. Load only the reference that matches the user's exact product, framework, or failure mode. Where a reference disagrees with this skill, this skill wins.

| Former skill | Reference | Description |
| --- | --- | --- |
| `agentcore` | [`references/skills/agentcore/SKILL.md`](references/skills/agentcore/SKILL.md) | Run agent-browser on AWS Bedrock AgentCore cloud browsers. Use when the user wants to use AgentCore, run browser automation on AWS, use a cloud browser with AWS credentials, or needs a managed browser session backed by AWS infrastructure. Triggers include "use agentcore", "run on AWS", "cloud browser with AWS", "bedrock browser", "agentcore session", or any task requiring AWS-hosted browser automation. |
| `beta-dx-walk` | [`references/skills/beta-dx-walk/SKILL.md`](references/skills/beta-dx-walk/SKILL.md) | Agent-led beta DX/UX readiness walk. Walk a product's critical user journeys as a skeptical first-time user and treat friction as a bug: anything that makes the user pause, guess, reread, or ask for help is a logged issue. At every step test two things - can the user understand what to do next, and can they recover when something fails. Triage each finding as blocks-beta, confuses-beta, or polish, with tried / expected / happened plus evidence, and end with a ship-or-hold readiness verdict. Use for beta readiness, onboarding and first-run QA, pre-launch UX gates, "walk the beta path", "is this ready for users", or "treat friction as a bug". Project-agnostic. |
| `browser-use` | [`references/skills/browser-use/SKILL.md`](references/skills/browser-use/SKILL.md) | Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, or extract information from web pages. |
| `dogfood` | [`references/skills/dogfood/SKILL.md`](references/skills/dogfood/SKILL.md) | Systematically explore and test a web application to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA", "exploratory test", "find issues", "bug hunt", "test this app/site/platform", or review the quality of a web application. Produces a structured report with full reproduction evidence -- step-by-step screenshots, repro videos, and detailed repro steps for every issue -- so findings can be handed directly to the responsible teams. |
| `electron` | [`references/skills/electron/SKILL.md`](references/skills/electron/SKILL.md) | Automate Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify, etc.) using agent-browser via Chrome DevTools Protocol. Use when the user needs to interact with an Electron app, automate a desktop app, connect to a running app, control a native app, or test an Electron application. Triggers include "automate Slack app", "control VS Code", "interact with Discord app", "test this Electron app", "connect to desktop app", or any task requiring automation of a native Electron application. |
| `gstack-qa` | [`references/skills/gstack-qa/SKILL.md`](references/skills/gstack-qa/SKILL.md) | QA lead with real browser testing. Tests your app, finds bugs, fixes them with atomic commits, generates regression tests. Use when the user says "QA", "test this", "find bugs", "exploratory test", "QA this", or "test the app". |
| `webapp-testing` | [`references/skills/webapp-testing/SKILL.md`](references/skills/webapp-testing/SKILL.md) | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. |
| `webwright` | [`references/skills/webwright/SKILL.md`](references/skills/webwright/SKILL.md) | Solve a user-specified web task code-as-action style by driving a local Playwright browser through one bash command at a time, saving screenshots and an action log into `final_runs/run_<id>/`, and visually verifying the result. Use when the user asks to automate a web task (search, filter, form-fill, multi-step flow, data extraction) and wants reusable scripts plus screenshot evidence rather than a one-shot answer. |
<!-- folded-skills:auto:end -->

---

Timeline

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