browser · v1.0 · 2026-11-08 · sha256 6bf99fe68a90bbcd

browser v1.0B

Immutable. This exact content never changes and is served at /api/v1/blob/6bf99fe68a90bbcd.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_pin5tsw42bfzhe2x/6bf99fe68a90bbcdf6b0591ebb0f3482112784e4617fcf8c738b5e9555c8a18d.json

Then /plugin install browser@markdownregistry-pin5tsw42bfzhe2x in Claude Code. It installs this exact version, the one graded B here, pinned to the commit it was graded at, and leaves it there.

---
name: browser
description: >-
  Drive a real or headless browser from the shell to verify web UI changes,
  click through flows, inspect console/network errors, or act inside the
  user's logged-in Chrome/Edge session. Use when fetch_url is not enough —
  SPAs, localhost dev servers, form interactions, visual checks, or
  authenticated sites (via agent-browser, lightpanda, bsk BrowserSkill, or
  playwright-cli).
metadata:
  version: "1.0"
---

# Browser automation from the shell

There is no dedicated browser tool in the schema on purpose: browser CLIs keep
a warm daemon between shell calls and cost zero tool-schema tokens on turns
that do not touch a browser. Drive them through `execute`.

If you only need to read a public static page, use `fetch_url` first. Reach
for a browser when the page needs JavaScript, you are verifying a UI you just
edited, or the task requires clicking, filling forms, screenshots, or the
user's existing login state.

## 1. Pick the right driver

Probe what is installed before your first call (`command -v agent-browser bsk lightpanda playwright-cli`):

| Task | Tool to use | Why |
|---|---|---|
| **Local dev preview (`localhost`), UI verification, public interactive pages** | `agent-browser` (default) | Fast Rust CLI + background daemon; `snapshot -i` returns compact `@e1` refs |
| **Fast read-only extraction on JS/SSR pages (no pixels needed)** | `agent-browser --engine lightpanda` or `lightpanda fetch --dump markdown <url>` | Zig engine, ~10x faster cold start and ~16x less memory than Chrome; no screenshots or extensions |
| **Sites requiring the user's existing logins / SSO / intranet (Feishu, GitHub, admin consoles)** | `bsk` (BrowserSkill) | Connects to the user's running Chrome/Edge in a separate orange Agent Window; shares cookies without hijacking their active tab; hands CAPTCHAs/2FA back to the user |
| **Fallback when `agent-browser` is absent, or exporting E2E tests** | `playwright-cli` | Session-persistent (`-s=<name>`) Playwright runner |

---

## 2. Clean / headless browser (`agent-browser`)

Chain commands in a single `execute` call when the steps do not depend on
reading intermediate refs; otherwise follow **open → `snapshot -i` → act on `@ref` → verify → `close`**.

Always pass `-i` (interactive-only) to `snapshot` unless you need static prose
— full snapshots waste tokens and inflate step counts. Refs (`@e1`, `@e2`)
belong to the snapshot that produced them; after any navigation or DOM change,
take a fresh `snapshot -i` before clicking the next ref.

```sh
# Open and read interactive refs
agent-browser open http://127.0.0.1:8881 && agent-browser snapshot -i

# Act on refs from the snapshot, then check console/errors
agent-browser click @e3 && agent-browser fill @e4 "hello" && agent-browser press Enter
agent-browser console && agent-browser errors
agent-browser screenshot /tmp/ui-check.png

# Always close when finished
agent-browser close
```

When `lightpanda` is on `PATH` and you do not need screenshots, visual layout,
or Chrome extensions, set `AGENT_BROWSER_ENGINE=lightpanda` (or run
`lightpanda fetch --dump markdown <url>` for one-shot reading).

### Fallback: `playwright-cli`

```sh
playwright-cli -s=dev open http://127.0.0.1:8881
playwright-cli -s=dev snapshot
playwright-cli -s=dev click e2
playwright-cli -s=dev close
```

---

## 3. Logged-in user browser (`bsk` / BrowserSkill)

Use `bsk` when the user wants work done inside accounts they are already
signed into in Chrome or Edge.

### Process-group rule (critical)

Each foreground `execute` call kills its process group when the command
returns. If a `bsk` command auto-starts the `bsk` daemon as a child, that
daemon is killed as soon as the `execute` call finishes.

1. Check status without auto-starting:
   ```sh
   BSK_AUTO_START=0 bsk doctor
   ```
2. If the daemon is not running, start it in a **managed background task** so
   it survives across turns, then wait a moment and re-check:
   ```
   execute(command="bsk daemon start --foreground", background=True)
   ```
3. If `extension connected` is still failing in `bsk doctor`, stop and ask the
   user to open the BrowserSkill extension popup in Chrome/Edge and enable the
   local connection.
4. Run every command with `BSK_AUTO_START=0` and always stop the session in
    cleanup (even on failure) so borrowed tabs return to the user's window:
   ```sh
   export BSK_AUTO_START=0
   bsk session start --json          # -> save session_id, e.g. ab12
   bsk navigate https://example.com --session ab12
   bsk observe --session ab12
   bsk click @e1 --session ab12
   bsk session stop ab12
   ```

Never run `bsk evaluate` on banking, SSO, or password-manager pages to read
tokens or secrets, and never borrow a user's existing tab unless the task
explicitly requires that open tab.