Navigate the browser to a URL. Optionally clear console and network logs before navigating (recommended when starting a new task).

Perform one or more browser actions in sequence. Batch multiple steps into one call.

Two ways to target an element — use whichever is more stable: • ref — accessibility ref from browser_snapshot (preferred). LLM-friendly: no selector guessing, survives CSS class churn, resistant to obfuscated build output. Each ref is pinned to the exact element captured in the snapshot, so it never silently drifts to a different element when the page reflows. If that element is removed or re-rendered, the action fails loudly ("stale ref" / element not found) — re-snapshot rather than retrying. Call browser_snapshot first to get refs like "e9", "e42", then pass them to actions: { action: "click", ref: "e9" }. • selector — raw CSS selector. Use when you already know it, or for elements not in the a11y tree.

Example ref flow:

1. browser_snapshot() → { snapshot, refs: [{ref: "e9", role: "button", name: "Sign in"}] }

2. browser_act({ commands: [{ action: "click", ref: "e9" }] })

Available actions: • click — click an element (supports left/right/middle button). Use button:'right' for context menus • hover — hover over an element for tooltips, dropdown menus, hover states • drag — drag an element to a target selector (column reorder, kanban) OR by pixel offset (column resize, sliders). Use target for element-to-element, offsetX/offsetY for precise pixel drag • clicklink — click a link/button by visible text (text-based; does not use ref/selector) • fill — fill an input field (clears first) • select — select a dropdown option • keypress — press a key (Enter, Tab, Escape, etc.) — keyboard action, no ref/selector needed • waitfor — wait for an element to appear • scrollto — scroll an element into view • wait — pause for N milliseconds (no target) • clearconsole — clear captured console logs (no target)

click, hover, drag, fill, select, waitfor, scrollto all accept either 'ref' or 'selector'. If both are provided, 'ref' wins. Refs are invalidated on navigation — re-snapshot if the page has changed.

PREFERRED DEBUGGING TOOL. Returns current URL, page title, console logs, dialogs (alert/confirm/prompt), and rich network requests in one call. Always call this before browser_screenshot. Network entries include: method, URL, query params (parsed), request body (JSON/form), request headers (auth masked), status code, response body (JSON), and duration_ms for performance analysis. Use url_filter and method_filter to focus on specific API calls. Use console_types to filter log levels.

Query DOM elements by CSS selector. Use to check element state, text, visibility, or values without taking a screenshot. Use visible_only and limit to avoid huge result sets on broad selectors.

Execute an authenticated fetch() request inside the page context. Inherits the page's cookies and session — same-origin requests work automatically, cross-origin requires CORS. Returns status, headers, and parsed body. Appears in browser_debug network log.

Return the accessibility tree of the current page with refs attached to interactive elements (buttons, links, textboxes, checkboxes, etc.). Use this INSTEAD of guessing CSS selectors from a screenshot — selectors break on class-name churn, refs don't.

Returns { url, snapshot: [...tree], refs: [{ref, selector, role, name, testId}, ...] }.

Each ref like "e9" maps internally to a stable selector. Pass refs to browser_act: browser_act({ commands: [ { action: "fill", ref: "e42", value: "user@example.com" }, { action: "click", ref: "e9" } ]})

Every node includes testId when the element has data-testid, data-test, or data-qa — use these as additional stability anchors. Refs are invalidated automatically on navigation — re-snapshot after any browser_navigate or URL change.

Use compact: true to drop pure layout wrappers (divs/spans with no role, no testId) and return a flatter tree focused on interactive content. Recommended for noisy apps with deeply-nested div soup.

Wait for the page URL to change and match a substring pattern. Use after actions that trigger redirects (JS redirects, auth redirects, SPA route changes). Returns current URL on timeout. Optionally chain a readiness gate via wait_for so you don't have to follow up with setTimeout/wait.

LAST RESORT. Returns a screenshot as base64. Expensive and unstructured. Only use when the problem is purely visual (layout, rendering glitch). Always try browser_debug and browser_query first.

Execute JavaScript in the page context and return the result. This is your ESCAPE HATCH for anything the other tools don't cover. Common use cases: • Read computed styles: getComputedStyle(el).backgroundColor • Append text to inputs without clearing: el.value += '...'; el.dispatchEvent(new Event('input', {bubbles:true})) • Type character-by-character for autocomplete: use dispatchEvent with input events per character • Drag-and-drop: create and dispatch mousedown/mousemove/mouseup or dragstart/drop events • Read JS app state: window.store, React devtools, etc. • Check visibility via CSS: getComputedStyle(el).display, opacity, visibility • Scroll inside a container: document.querySelector('.container').scrollTop += 500 The code is evaluated as an expression — use an IIFE for multi-statement code.

Scroll the page, scroll within a specific container element (e.g. AG-Grid viewport, chat panel, sidebar), or scroll an element into view. Use 'container' to scroll inside scrollable divs instead of the page.

Close and reopen the browser session. Use when the page is dead, crashed, or stuck after navigating to an external site. Optionally navigate to a URL immediately after restart.

Upload one or more files to a file input element. Use the CSS selector to target the input and provide absolute file paths.

Wait for a specific network response matching URL pattern and/or method. Returns the response with status and JSON body. Use after triggering an action to wait for its API call to complete instead of guessing with wait times. url_pattern accepts a single substring OR an array of substrings (any-of match — resolves on the first matching response).

Switch the browser session into a device emulation profile (iPhone / iPad / Android tablet / desktop reset / custom). Emulation lives on the browser context — it persists across browser_navigate calls until you swap to another device or call browser_restart.

IMPORTANT behaviors: • Swapping devices recreates the browser context but cookies + localStorage are PRESERVED (via persistent storageState). Pages behind auth stay logged in across swaps. The tool auto-navigates back to the URL you were on. IndexedDB is not preserved — PWAs that store auth tokens there may require re-login. • innerWidth: 980 on a mobile emulation is NOT a bug. It means the current page has no and is using Chrome's legacy fallback. Check verified.layout_mode — it will be "legacy-980-fallback" in this case. The authoritative signals that emulation is working are: userAgent, pointer_coarse, hasTouch, devicePixelRatio. • browser_restart always clears emulation (back to desktop). • Not supported in REAL_CHROME mode (returns an error).

Presets and natural viewports (portrait): • iphone-15-pro-max (430×932), iphone-15-pro (393×852), iphone-15 (393×852), iphone-se (375×667) • galaxy-s24 (360×800) • ipad-pro-13 (1024×1366), ipad-pro-11 (834×1194), ipad-mini (768×1024) • galaxy-tab-s9 (800×1280) • desktop-chrome (1280×800, DPR 1, no touch — use this to reset) • custom — requires custom.userAgent + custom.viewport.{width,height}

Returns { ok, active, previous_url, previous_url_restored, verified, checks, warnings? }. ok: true as long as the essential fields (UA substring + devicePixelRatio) match; soft drift in hasTouch or pointer_coarse surfaces as warnings[] without flipping ok. On hard failure: { ok: false, error, verified, checks }.