use_browser
Control a persistent Chrome browser to navigate, click, type, and capture page screenshots, markdown, and DOM automatically.
Instructions
Control persistent Chrome browser with automatic page capture.
Every DOM action (navigate, click, type, select, eval) auto-captures to the session dir:
{prefix}.png — viewport screenshot
{prefix}.md — page content as structured markdown
{prefix}.html — full rendered DOM
{prefix}-console.txt — browser console messages
Prefer reading these files to using 'extract' or 'screenshot' whenever possible. Actions on a page showing token-shaped content (Slack/GitHub/1Password tokens, otpauth:// URIs) or any data-sen-secret element write no capture files, token-shaped values are redacted from all output, and eval refuses outright while any data-sen-secret element is on the page — an accident guard against a cooperating agent's own reads, not a security boundary. A secret with no distinctive shape (bare TOTP seed, backup code) is captured like any other text until it is marked: mark it with 'set_attr' name 'data-sen-secret' as soon as the action that revealed it returns, before any other action on that page. Capture files written before the mark keep the value and are not deleted, so don't read them back. 'set_attr' is a write-only setter for exactly 'data-sen-nonce' or 'data-sen-secret' that is exempt from that eval restriction (see 'help' for details) — use it, not eval, to write onto the page while a secret is present.
Schema: 4 parameters — action, selector (CSS/XPath or null), payload (string or object), timeout (ms). selector targets a DOM element (null/omit for navigation, eval, tab management, etc.). payload is a string for simple actions (navigate=URL, type=text, eval=JS, keyboard_press=key). payload is an object for structured actions (set_viewport={width,height}, drag_drop={target}, etc.) — a JSON-encoded string of the same object works too. Tabs are tracked as sticky state; use switch_tab to change the active tab. Use action='help' for full per-action payload shapes.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform. action='help' lists all actions with payload shapes. | |
| payload | No | Extra data for the action. Both a plain object and an equivalent JSON-encoded string are accepted for every structured shape below (e.g. set_viewport accepts either {width:390,height:844} or '{"width":390,"height":844}'). Literal string for code/free-text actions, taken as-is and never JSON-parsed even if it happens to look like JSON (eval=JS source, type=literal text, await_text=literal text to wait for, select=literal option value). String or object for simple cases (navigate=URL, set_profile=name, new_tab=URL, attr=attribute name or {selector,attr}). Structured object (or its JSON-string equivalent) for the rest: set_viewport={width,height,mobile?} (no bare-string form), keyboard_press=key string or {key,modifiers:{shift?,ctrl?,alt?,meta?}}, extract=format string or {format:'text'|'html'|'markdown',selector?}, screenshot=path string or {path,fullpage?,selector?}, scroll=direction string or {deltaX?,deltaY?,selector?}, drag_drop=target selector string, {x,y} target coords, or {source,target}, mouse_move={x,y,steps?,fromX?,fromY?} (no bare-string form), file_upload=path string, JSON array-of-paths string, or {selector,files:[...]}, get_console_messages={since:epochMs} or a bare epoch-ms timestamp, switch_tab=tab index/url-substring/title-substring). See action='help' for per-action payload shapes. | |
| timeout | No | Timeout in ms for await_element / await_text actions. | |
| selector | No | CSS or XPath selector — what to act on. Null/omitted for actions that don't target an element (navigate, eval, list_tabs, etc.). XPath must start with / or //. dialog::accept and dialog::dismiss are special selectors for handling open dialogs. | |
| tab_index | No | Legacy: behaves like switch_tab. Sets the active tab to this index before running the action. Prefer the switch_tab action. |