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 browserconnect before any other tool. Mode launch spawns (or reuses) a Chrome process; mode attach connects to a running Chrome via browserurl 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: browserscreenshot, browserdom, browseraccessibility, browserexporthar, browserperformancestoptrace, browser_pdf. Pass the returned path to a subagent for reading when available.

Navigation and waiting

browsernavigate accepts http/https only. After navigation, use browserwait (strategy navigation or selector) to confirm the page settled before interacting. For text-triggered flows use browserwaitfor_text.

Tool surface by group

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

Payload discipline