| name | browser |
| description | 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. |
| when_to_use | take a screenshot of the page, click a button on the page, fill out the form in the browser, navigate to a URL in the browser, run a Lighthouse audit, Lighthouse performance audit, capture network requests as a HAR file, record network traffic HAR, check or inspect the accessibility tree, intercept network requests, stub an API response in the browser, mock network calls, emulate an iPhone or Android device, browser automation, automate the browser, end-to-end testing in Chrome. Not for build failures, compiler errors, or code edits. |
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 |
