# Browser

> Controls a live Chrome browser through a persistent puppeteer-core MCP connection — click, type, hover, drag, fill forms; navigate pages; take screenshots and export PDFs; read the DOM and accessibility tree; run Lighthouse audits and Core Web Vitals traces; intercept, record, stub, or block network requests; export HAR traffic; emulate devices and network conditions; manage browser storage; upload and download files. Use when interacting with or automating a running browser, clicking elements, taking screenshots, running Lighthouse, capturing network traffic as HAR, checking the accessibility tree, intercepting or stubbing requests, or emulating a device or viewport. Not for: web search or fetching public URLs without a browser session (use web-research), reading a static HTML file already on disk, fixing TypeScript or JavaScript build or compile errors, debugging source code without a running page, or tasks that don't require controlling a live browser.

- Skill: `ryanthedev/browser` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add ryanthedev/browser`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ryanthedev/browser/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: ryanthedev (https://skillmd.com/u/ryanthedev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ryanthedev/browser

---


# browser

Persistent Chrome/CDP control via puppeteer-core. The primary interaction model
is snapshot → stable ref → action. Selectors and coordinates are fallbacks only.
Large outputs (screenshots, DOM, AX trees, HAR, traces) are always written to
disk — the tool returns a file path, never raw bytes.

## Prerequisites

Call `browser_connect` before any other tool. Mode `launch` spawns (or reuses)
a Chrome process; mode `attach` connects to a running Chrome via `browser_url`
or `ws_endpoint`.

## Primary loop: snapshot → ref → act

```
browser_snapshot          → returns compact AX tree; every interactive node carries a stable ref id
browser_click(ref=...)    → act on the ref (also: browser_type, browser_hover, browser_select, browser_fill_form, browser_press_key, browser_drag)
browser_snapshot          → verify the new state
```

A `stale_ref` error means the page changed; take a new snapshot. Selector/coordinate
targeting is the fallback when a ref is unavailable.

## Screenshot, DOM, and AX — route to a subagent when available

Screenshots, DOM trees, and accessibility trees are large (50 KB–5 MB).
Loading them directly bloats the main context. Use the host's subagent tool
when available: dispatch a small reviewer that reads the file path and returns
a text summary, so the artifact never enters this conversation. If the host has
no subagent surface, summarize inline only when the artifact is small enough;
otherwise use local deterministic tools or ask how to proceed.

```
Dispatch Agent:
  model: haiku
  description: "browser: analyze [screenshot|dom|accessibility]"
  prompt: |
    The browser tool wrote an artifact to: <PATH>
    Read that file with the Read tool.
    Return a concise text summary: what the page shows, key elements,
    errors or state, and the specific answer to: <USER_QUESTION>
    Return text only — no raw HTML, JSON, or image data.
```

Tools that produce large artifacts: `browser_screenshot`, `browser_dom`,
`browser_accessibility`, `browser_export_har`, `browser_performance_stop_trace`,
`browser_pdf`. Pass the returned path to a subagent for reading when available.

## Navigation and waiting

`browser_navigate` accepts http/https only. After navigation, use `browser_wait`
(strategy `navigation` or `selector`) to confirm the page settled before
interacting. For text-triggered flows use `browser_wait_for_text`.

## Tool surface by group

Full parameter details in the references below. Load the relevant one when
planning work in that group.

| Group | Reference |
|---|---|
| Snapshot + refs interaction · Navigation · Read + extract | `references/interaction.md` in this skill directory |
| Performance · Lighthouse · HAR · Network routing · Throttling | `references/perf-network.md` in this skill directory |
| Storage · Device emulation · Geolocation · Capture (PDF / screencast / upload / download) | `references/storage-capture.md` in this skill directory |

## Payload discipline

| Artifact | Where it lives | In main context? |
|---|---|---|
| Screenshot PNG | file path from `browser_screenshot` | Prefer subagent; inline only if small enough |
| DOM HTML | file path from `browser_dom` | Prefer subagent; inline only if small enough |
| AX tree JSON | file path from `browser_accessibility` | Prefer subagent; inline only if small enough |
| HAR file | file path from `browser_export_har` | Prefer subagent; inline only if small enough |
| Performance trace | file path from `browser_performance_stop_trace` | No — analyze via `browser_analyze_insight` |
| PDF | file path from `browser_pdf` | Prefer subagent; inline only if small enough |
| Subagent text summary | returned text | Yes |
| Direct tool output (small) | inlined in result | Yes |