agent-browser

Files (2)

• SKILL.md
• UPSTREAM.md

SKILL.md (first lines)

# agent-browser

> **Origin.** Written by Vercel Labs in [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) (Apache-2.0), pinned at `dac13bb`.
> The upstream text below is verbatim except the edits listed in [UPSTREAM.md](UPSTREAM.md). Our additions live under **Field notes** at the end.

Fast browser automation CLI for AI agents. Chrome/Chromium via CDP with accessibility-tree snapshots and compact `@eN` element refs.

Install: `npm i -g agent-browser && agent-browser install`

## Start here

This file is a discovery stub, not the usage guide. Before running any `agent-browser` command, load the actual workflow content from the CLI:

```bash
agent-browser skills get core             # start here — workflows, common patterns, troubleshooting
agent-browser skills get core --full      # include full command reference and templates
```

The CLI serves skill content that always matches the installed version, so instructions never go stale. The content in this stub cannot change between releases, which is why it just points at `skills get core`.

## Specialized skills

Load a specialized skill when the task falls outside browser web pages:

```bash
agent-browser skills get electron          # Electron desktop apps (VS Code, Slack, Discord, Figma, ...)
agent-browser skills get slack             # Slack workspace automation
agent-browser skills get dogfood           # Exploratory testing / QA / bug hunts
agent-browser skills get derive-client     # Record a HAR, derive a standalone API client for a site
agent-browser skills get vercel-sandbox    # agent-browser inside Vercel Sandbox microVMs
agent-browser skills get protected-vercel-deployments  # Access protected Vercel deployments
agent-browser skills get agentcore         # AWS Bedrock AgentCore cloud browsers
```

Run `agent-browser skills list` to see everything available on the installed version.

## Why agent-browser

- Fast native Rust CLI, not a Node.js wrapper
- Works with any AI agent (Cursor, Claude Code, Codex, Continue, Windsurf, etc.)
- Chrome/Chromium via CDP with no Playwright or Puppeteer dependency
- Accessibility-tree snapshots with element refs for reliable interaction
- Sessions, authentication vault, state persistence, video recording
- Specialized skills for Electron apps, Slack, exploratory testing, cloud providers

## Observability Dashboard

The dashboard runs independently of browser sessions on port 4848 and can also be opened through a proxied or forwarded URL such as `https://dashboard.agent-browser.localhost`. Agents should stay on the dashboard origin: session tabs, status, and stream traffic are proxied internally, so session ports do not need to be exposed.

## Field notes

Evidence: 130 real sessions, 3,492 `agent-browser` calls, mined from local agent logs (method in [docs/field-data.md](https://github.com/imaginaerumai/field-tested-skills/blob/main/docs/field-data.md)).

1. Close every session you open. Measured ratio was about 1,356 `open` to 320 `close`, and 47 of 130 sessions ended without a close. Headless Chromium renders on the CPU through SwiftShader, so a leaked tab on an animating page pins a core until reboot. One user hit two leaked GPU helpers at about 110% CPU each. End every flow with `agent-browser close`, including the error path. If your shell supports it, `trap 'agent-browser close' EXIT`. Recovery tool: the `purge-stress` skill.
2. Snapshot before every click after the page changes. `Unknown ref: eNN` appeared 19 times in 12 sessions, always from chained `click @eN && click @eM` after navigation. Refs belong to one snapshot. Re-snapshot, then click.
3. Dismiss overlays first. `Element @eN is covered by <div...>` appeared 15 times in 12 sessions, mostly cookie consent banners. Accept or close the banner as the first action on a new site.
4. Wrap `eval` code in an IIFE. `Identifier 'x' has already been declared` appeared 11 times in 9 sessions, because each `eval` runs in the same page realm. Use `(() => { ... })()`.
5. Give commands a real timeout. 38 calls in 21 sessions were killed by a 15 to 30 second shell timeout, `close` included. Allow at least 60 seconds for navigation-heavy commands.
6. Reuse the user's login instead of re-authenticating. In about 6 sessions the user offered to log in for the agent about 12 times. Ask once, then reuse their state: `agent-browser connect <port>` attaches to a browser they started with remote debugging, and `--profile <name>` reuses a Chrome profile's login (both from `agent-browser --help`). Do not script SSO.

From imaginaerumai/field-tested-skills, Apache-2.0.

More from imaginaerumai/field-tested-skills