Navigate the browser to a URL and wait for DOM content to load. Use when the user wants to go to a specific webpage, URL, or link.

For read tasks ("go to X and tell me Y"), prefer pilot_get — it returns full readable content + interactive elements in one call, eliminating a follow-up snapshot call.

Parameters:

• url: The URL to navigate to (e.g., "https://example.com" or relative paths)

Returns: Confirmation message with the HTTP status code, content preview, and interactive elements.

Errors:

• "Invalid URL": The URL format is malformed. Provide a complete URL including the protocol.

• Timeout (15s): The page took too long to load. Try pilot_navigate again or check the URL.

• "Navigation denied": The URL was rejected by security validation (e.g., file:// on restricted origins).

Navigate back to the previous page in browser history. Use when the user wants to go back to the prior page they visited.

Parameters: (none)

Returns: The URL of the page after navigating back.

Errors:

• "No previous page in history": There is nothing to go back to. Use pilot_navigate instead.

• Timeout (15s): The previous page took too long to load.

Navigate forward to the next page in browser history. Use when the user wants to go forward after using pilot_back.

Parameters: (none)

Returns: The URL of the page after navigating forward.

Errors:

• "No next page in history": There is nothing to go forward to. Use pilot_navigate instead.

• Timeout (15s): The next page took too long to load.

Reload the current page, waiting for DOM content to load. Use when the user wants to refresh the page, clear dynamic state, or retry a failed load.

Parameters: (none)

Returns: The URL of the reloaded page.

Errors:

• Timeout (15s): The page took too long to reload. Try again or check network connectivity.

Navigate to a URL and return its full readable content + interactive elements in one call.

Use this as the primary tool for "go to X and find Y" read tasks. It combines navigation and content extraction, eliminating the need for a separate snapshot call.

Parameters:

• url: The URL to fetch

Returns: Page title, readable body text (up to 1500 chars), and interactive elements. Enough context to answer most read questions without additional tool calls.

Errors:

• Timeout (15s): The page took too long to load.

Capture an accessibility tree snapshot of the page with @eN refs for element selection. Use when the user wants to see the page structure, find elements to interact with, or get refs for click/fill/hover. This is the primary way to understand what is on the page. Refs from this snapshot are used by pilot_click, pilot_fill, pilot_hover, pilot_select_option, and most other interaction tools.

Parameters:

• selector: CSS selector to scope the snapshot to a specific subtree (e.g., "#main-content")

• interactive_only: Set to true to show only interactive elements (buttons, links, inputs) — saves tokens on large pages

• compact: Set to true to remove empty structural nodes from the tree

• depth: Limit the tree depth (0 = root only). Useful for reducing token usage on deeply nested pages

• include_cursor_interactive: Set to true to scan for elements with cursor:pointer, onclick, or tabindex that are not in the ARIA tree — returns @cN refs

• max_elements: Maximum elements to include before truncating (saves tokens on very large pages)

• structure_only: Set to true to show tree structure without text content — saves tokens when you only need the element hierarchy

• output_file: Set to true to save the snapshot to a temp file instead of returning inline. Returns the file path — read with the Read tool when needed. Useful when the snapshot is large and you only need it on demand.

Returns: Text representation of the accessibility tree with @eN refs (and @cN refs if include_cursor_interactive is true). If output_file=true: returns only the file path (e.g. /tmp/pilot-snap-abc123.txt).

Errors:

• Timeout: The page is too complex or unresponsive. Try scoping with selector or using max_elements.

Compare the current page state against the previously captured snapshot, showing a unified diff of what changed. Use when the user wants to verify the effect of an action (click, fill, navigation), check if dynamic content loaded, or see what changed on the page without re-reading the entire snapshot. The first call stores a baseline; subsequent calls diff against it.

Parameters:

• selector: CSS selector to scope both snapshots to a specific subtree

• interactive_only: Set to true to only diff interactive elements (buttons, links, inputs)

Returns: Unified diff text showing added (+) and removed (-) lines between snapshots.

Errors:

• "No baseline snapshot": This is the first call — a baseline will be stored for future diffs.

• Timeout: The page is unresponsive.

Find an element by visible text, label, placeholder, or role — without running a full snapshot. Use when you know what you want to click or fill but don't need to see the entire page tree. Returns a @eN ref immediately usable by pilot_click, pilot_fill, pilot_hover, and other interaction tools. Saves tokens compared to pilot_snapshot when you only need one element.

Parameters:

• text: Visible text content of the element (e.g., "Sign in", "Submit")

• label: ARIA label or associated text (e.g., "Email address", "Password")

• placeholder: Input placeholder text (e.g., "Search...", "Enter email")

• role: ARIA role to match (e.g., "button", "link", "textbox") — combine with text for precision

• exact: Set to true for exact text/label match (default: false, substring match)

Returns: A @eN ref for the found element and a description of what was found.

Errors:

• "Element not found": No element matched the criteria. Verify the text/label or run pilot_snapshot to inspect the page.

• "Multiple elements found": More than one element matched. Add role or use exact=true to narrow it down.

Take a PNG screenshot with red overlay boxes and ref labels at each @eN/@cN element position. Use when the user wants a visual debug overlay showing where each snapshot ref is located on the page, or needs to verify element positions visually. Requires a prior pilot_snapshot call to populate the ref positions. For a clean visual capture without debug overlays, use pilot_screenshot instead.

Parameters:

• output_path: Optional file path to save the annotated screenshot (default: temp directory)

Returns: The annotated screenshot as a base64 PNG image and the file path where it was saved.

Errors:

• "No ref positions": Run pilot_snapshot first to capture element positions before taking an annotated screenshot.

• Timeout: The page is unresponsive.

Click an element on the page using a ref from pilot_snapshot or a CSS selector. Use when the user wants to press a button, follow a link, check a checkbox, or interact with any clickable element. Auto-routes clicks on elements to pilot_select_option.

Parameters:

• ref: Element reference from snapshot (e.g., "@e3") or a CSS selector (e.g., "button.submit")

• button: Mouse button to click — "left" (default), "right" (context menu), or "middle"

• double_click: Set to true for a double-click instead of single click

Returns: Confirmation with the clicked ref and the current URL after navigation (if any).

Errors:

• "Element not found": The ref is stale or the selector matches nothing. Run pilot_snapshot to get fresh refs.

• "Element is not clickable": The element exists but is obscured or disabled. Try scrolling to it first with pilot_scroll.

• "Timeout": The click triggered a navigation that took too long. The page may still be loading.

Hover the mouse over an element, triggering hover states, tooltips, and dropdown menus. Use when the user wants to reveal hidden content, trigger a CSS :hover effect, or inspect tooltip text.

Parameters:

• ref: Element reference from snapshot (e.g., "@e7") or a CSS selector

Returns: Confirmation with the hovered element ref.

Errors:

• "Element not found": The ref is stale. Run pilot_snapshot to get fresh refs.

• Timeout (5s): The element could not be hovered — it may be off-screen or detached.

Fill an input or textarea with new text, replacing any existing content. Use when the user wants to enter text into a form field, search box, or editable element. Prefer pilot_fill over pilot_type for inputs because it is faster and clears existing content automatically.

Parameters:

• ref: Element reference from snapshot (e.g., "@e12") or a CSS selector (e.g., "#email")

• value: The text to fill into the element

Returns: Confirmation with the filled element ref.

Errors:

• "Element not found": The ref is stale. Run pilot_snapshot to get fresh refs.

• "Element is not editable": The element is read-only or disabled. Try pilot_click to enable it first.

• Timeout (5s): The element could not be filled.

Select an option from a dropdown element by value, label, or visible text. Use when the user wants to choose a dropdown option, select from a combobox, or pick from a list. Note: clicking an in pilot_snapshot is auto-routed here.

Parameters:

• ref: The element reference from snapshot (e.g., "@e5") or a CSS selector

• value: The option's value attribute, label, or visible text to match

Returns: Confirmation with the selected value and element ref.

Errors:

• "No option matched": The value does not match any option. Check the exact option text or value attribute via pilot_page_html.

• "Element not found": The ref is stale or does not point to a element. Run pilot_snapshot.

Type text character-by-character into the currently focused element, simulating real keyboard input. Use when the user wants to type into a contenteditable div, rich text editor, or a field that reacts to individual keystrokes (e.g., autocomplete, keypress events). For standard / elements, prefer pilot_fill which is faster.

Parameters:

• text: The text string to type

• submit: Set to true to press Enter after typing (useful for search fields and forms)

Returns: Character count typed and whether Enter was pressed.

Errors:

• "No element is focused": Nothing is focused on the page. Use pilot_click on the target field first.

• Timeout: The page became unresponsive during typing.

Press a keyboard key or key combination on the page. Use when the user wants to press Enter to submit a form, Tab to move between fields, Escape to close a modal, ArrowDown to navigate a list, or use any keyboard shortcut.

Parameters:

• key: Key name or combination (e.g., "Enter", "Tab", "Escape", "ArrowDown", "Backspace", "Shift+Enter", "Control+a")

Returns: Confirmation of the key pressed.

Errors:

• "Unknown key": The key name is not recognized. Use standard Playwright key names (see docs.playwright.dev/key-input).

Drag one element and drop it onto another element on the page. Use when the user wants to move an element, reorder items in a drag-and-drop list, or interact with a drag-and-drop UI.

Parameters:

• start_ref: The source element reference from snapshot (e.g., "@e3") or CSS selector to drag from

• end_ref: The target element reference from snapshot (e.g., "@e5") or CSS selector to drop onto

Returns: Confirmation with source and target refs.

Errors:

• "Element not found": Either ref is stale. Run pilot_snapshot to get fresh refs.

• Timeout (5s): The drag operation could not be completed. The elements may not support drag-and-drop.

Scroll the page or a specific element into view. Use when the user wants to scroll down a long page, scroll to the bottom, scroll to the top, or scroll a specific element into the viewport. With a ref, scrolls the element into view. Without a ref, scrolls the page by one viewport height or to a specific position.

Parameters:

• ref: Element reference from snapshot (e.g., "@e20") or CSS selector to scroll into view (omit for page scroll)

• direction: Page scroll direction when no ref is provided — "up", "down", "top", or "bottom" (default: "bottom")

Returns: Confirmation of what was scrolled and in which direction.

Errors:

• "Element not found": The ref is stale. Run pilot_snapshot to get fresh refs.

• Timeout (5s): The element could not be scrolled into view.

Wait for a specific condition before proceeding — an element to appear, the network to become idle, or the page to finish loading. Use when the user wants to wait for a dynamic element to load, wait for AJAX/fetch requests to complete, or wait for a modal/spinner to appear or disappear.

Parameters:

• ref: Element reference from snapshot (e.g., "@e10") or CSS selector to wait for

• state: What to wait for — "visible" (element appears, default), "hidden" (element disappears), "networkidle" (no network requests for 500ms), or "load" (page load event)

• timeout: Maximum wait time in milliseconds (default: 15000)

Returns: Confirmation of what was waited for and its state.

Errors:

• "Timeout waiting for element": The element did not reach the expected state in time. Increase timeout or check the selector.

• "Nothing to wait for": Neither ref nor state was provided. Supply at least one.

Upload one or more files to a file input element on the page. Use when the user wants to attach files, upload images, or submit documents through a file input field.

Parameters:

• ref: The file input element reference from snapshot (e.g., "@e8") or a CSS selector pointing to an

• paths: Array of absolute file paths to upload (e.g., ["/home/user/photo.png", "/home/user/doc.pdf"])

Returns: Confirmation with file names and sizes uploaded.

Errors:

• "File not found": One or more paths do not exist on the filesystem. Verify the file paths.

• "Element not found": The ref is stale or does not point to a file input. Run pilot_snapshot.

• "Not a file input": The element is not an .

Extract clean text from the page (strips script/style/noscript/svg).

Get innerHTML of a selector/ref, or full page HTML if none provided.

Get all links on the page as text + href pairs.

Extract all form elements on the page as structured JSON with their types, names, IDs, and current values. Use when the user wants to understand form structure, see all input fields with their current values, check form methods and actions, or plan form filling automation. Password field values are redacted for security.

Parameters: (none)

Returns: JSON array of form objects, each containing the form's index, action URL, method, id, and an array of field objects with tag, type, name, id, placeholder, required, and value.

Errors: None — returns empty array "[]" if no forms exist on the page.

Get all HTML attributes of a specific element as a JSON object. Use when the user wants to inspect an element's attributes (data-, aria-, class, id, href, src, etc.), check custom data attributes, or debug attribute-related issues.

Parameters:

• ref: Element reference from snapshot (e.g., "@e3") or CSS selector

Returns: JSON object mapping attribute names to their values.

Errors:

• "Element not found": The ref is stale. Run pilot_snapshot to get fresh refs.

Get the computed CSS property value for a specific element. Use when the user wants to check styling details (colors, fonts, dimensions, spacing), debug CSS issues, or verify that styles are applied correctly. Returns the final computed value after all CSS rules and inheritance are resolved.

Parameters:

• ref: Element reference from snapshot (e.g., "@e3") or CSS selector

• property: CSS property name in kebab-case or camelCase (e.g., "color", "font-size", "backgroundColor", "display")

Returns: The computed CSS property value as a string (e.g., "rgb(255, 0, 0)", "16px", "flex").

Errors:

• "Element not found": The ref is stale. Run pilot_snapshot to get fresh refs.

Check the current state of an element — whether it is visible, hidden, enabled, disabled, checked, editable, or focused. Use when the user wants to verify an element's condition before interacting with it, check if a button is disabled, confirm a checkbox is checked, or debug why an interaction is failing.

Parameters:

• ref: Element reference from snapshot (e.g., "@e3") or CSS selector

• property: The state to check — "visible", "hidden", "enabled", "disabled", "checked", "editable", or "focused"

Returns: Boolean string "true" or "false" indicating the element's state for the requested property.

Errors:

• "Element not found": The ref is stale. Run pilot_snapshot to get fresh refs.

Retrieve browser console messages (console.log, console.warn, console.error) from a circular buffer. Use when the user wants to debug JavaScript errors, check application logs, inspect warnings, or see what the page is printing to the console.

Parameters:

• level: Filter messages by log level — "error" (includes warnings), "warning", "info", or "all" (default: all)

• clear: Set to true to clear the buffer after reading (useful for checking new messages after an action)

Returns: Timestamped list of console messages with their log level, or "(no console messages)" if the buffer is empty.

Errors: None — returns empty message if no entries match the filter.

Retrieve network requests (XHR, fetch, navigation, static assets) from a circular buffer. Use when the user wants to debug API calls, check request/response status codes, monitor network activity, or verify that a request was made after an action.

Parameters:

• clear: Set to true to clear the buffer after reading (useful for isolating new requests after an action)

Returns: List of requests showing method, URL, status code, duration in ms, and response size in bytes. Or "(no network requests)" if the buffer is empty.

Errors: None — returns empty message if no entries exist.

Retrieve captured browser dialog messages (alert, confirm, prompt) from a circular buffer. Use when the user wants to see what native dialogs appeared on the page, check prompt text, or verify that a dialog was triggered after an action. Note: configure auto-handling with pilot_handle_dialog to prevent dialogs from blocking page interaction.

Parameters:

• clear: Set to true to clear the buffer after reading

Returns: Timestamped list of dialogs showing type (alert/confirm/prompt), message text, and the action taken (accepted/dismissed) with any response text. Or "(no dialogs captured)" if empty.

Errors: None — returns empty message if no dialogs were captured.

Execute a JavaScript expression or function in the browser page context and return the result. Use when the user wants to run custom JavaScript on the page, read or modify DOM elements, extract data, or perform calculations. Supports async/await — use "await" to wait for promises. Multi-line code with await is automatically wrapped in an async IIFE.

Parameters:

• expression: JavaScript expression to evaluate (e.g., "document.title", "JSON.stringify(localStorage)", "await fetch('/api').then(r => r.json())"). Maximum 50 KB.

Returns: The expression result as a string, or pretty-printed JSON for objects/arrays.

Errors:

• "Evaluation failed": The JavaScript threw an error. Fix the expression syntax or handle the error in the page context.

• "Promise rejected": An awaited promise rejected. Check the API endpoint or async logic.

Retrieve all cookies for the current page context as a JSON array. Use when the user wants to inspect cookies, debug authentication state, check session tokens, or verify that cookies were set correctly. For setting individual cookies, use pilot_set_cookie; for bulk import from a real browser, use pilot_import_cookies.

Parameters: (none)

Returns: JSON array of cookie objects with name, value, domain, path, expires, httpOnly, secure, and sameSite attributes.

Errors: None — returns empty array "[]" if no cookies exist.

Read or write browser web storage (localStorage and sessionStorage). Use when the user wants to inspect stored application data, check feature flags, debug session state, or set a specific localStorage value. Sensitive values (tokens, secrets, API keys) are automatically redacted for security.

Parameters:

• set_key: If provided, sets this key in localStorage to the value in set_value

• set_value: The value to set for set_key in localStorage (omit to read all storage instead)

Returns: When reading: JSON object with localStorage and sessionStorage contents (sensitive values redacted as "[REDACTED — N chars]"). When writing: Confirmation of the key set.

Errors: None — returns empty storage objects if no data exists.

Security: Values matching patterns like "eyJ..." (JWTs), "sk-..." (API keys), or keys containing "token", "secret", "password" are auto-redacted.

Measure page load performance metrics from the Navigation Timing API. Use when the user wants to diagnose slow page loads, benchmark performance, or identify bottlenecks in DNS lookup, connection, server response, or DOM parsing.

Parameters: (none)

Returns: Table of timing metrics in milliseconds — dns, tcp, ssl, ttfb (time to first byte), download, domParse, domReady, and load.

Errors:

• "No navigation timing data available": The page has not completed a navigation or was loaded via non-standard means. Navigate to the page first with pilot_navigate, then reload.

Take a PNG screenshot of the current page or a specific element. Use when the user wants to capture what the page looks like visually, save a screenshot to disk, or capture a specific element's appearance. For a visual debug overlay with ref labels, use pilot_annotated_screenshot instead.

Parameters:

• ref: Element reference from snapshot (e.g., "@e3") or CSS selector to screenshot a specific element (omit for full page)

• full_page: Set to false for viewport-only capture (default: true, captures the entire scrollable page)

• output_path: File path to save the screenshot (default: /tmp/pilot-screenshot.png). Must be within the allowed output directory

• clip: Crop region as {x, y, width, height} pixel coordinates for a specific area of the page

Returns: The screenshot as a base64 PNG image and the file path where it was saved.

Errors:

• "Output path must be within ...": The path is outside the allowed directory. Set PILOT_OUTPUT_DIR or use /tmp.

• "Element not found": The ref is stale. Run pilot_snapshot to get fresh refs.

Save the current page as a PDF document in A4 format. Use when the user wants to export the page as a downloadable PDF, save a receipt, or archive a page for offline reading.

Parameters:

• output_path: File path to save the PDF (default: /tmp/pilot-page.pdf). Must be within the allowed output directory

Returns: Confirmation with the file path where the PDF was saved.

Errors:

• "Output path must be within ...": The path is outside the allowed directory. Set PILOT_OUTPUT_DIR or use /tmp.

• "Page is not HTML": The current page is a non-HTML resource (e.g., a binary download) and cannot be exported as PDF.

Capture full-page screenshots at three standard responsive breakpoints — mobile (375x812), tablet (768x1024), and desktop (1280x720). Use when the user wants to preview how a page looks across different screen sizes, test responsive design, or generate viewport comparison screenshots. The browser viewport is restored to its original size after capture.

Parameters:

• output_prefix: File path prefix for the saved screenshots (default: /tmp/pilot-responsive). Files are saved as {prefix}-mobile.png, {prefix}-tablet.png, {prefix}-desktop.png

Returns: List of viewport names, dimensions, and file paths for each screenshot.

Errors:

• "Output path must be within ...": The prefix path is outside the allowed directory.

• Timeout: The page took too long to render at one of the viewports.

Generate a text diff comparing the visible content of two URLs — useful for comparing staging vs production, before vs after deployments, or detecting content differences between pages. Use when the user wants to see what text differs between two pages, verify a deployment did not break content, or compare two versions of the same site. Strips scripts, styles, and SVG before comparing.

Parameters:

• url1: The first URL to navigate to and capture (shown as removed lines "---" in the diff)

• url2: The second URL to navigate to and capture (shown as added lines "+++" in the diff)

Returns: Unified diff text showing lines removed from url1 and added in url2.

Errors:

• "Invalid URL": Either URL is malformed. Provide complete URLs with protocol.

• Timeout (15s): A page took too long to load. Check the URL or network connectivity.

List all open browser tabs with their IDs, URLs, titles, and which tab is currently active. Use when the user wants to see what tabs are open, find a specific tab by title or URL, or check which tab is active before switching.

Parameters: (none)

Returns: Numbered list of tabs showing [id], title, URL, and an arrow (→) marking the active tab.

Errors: None — returns empty list if no tabs exist (unlikely in normal operation).

Open a new browser tab, optionally navigating to a URL. Use when the user wants to open a link in a new tab, create a blank tab, or work with multiple pages simultaneously.

Parameters:

• url: Optional URL to navigate to in the new tab (omit for a blank about:blank tab)

Returns: The new tab's ID and URL (if provided).

Errors:

• "Invalid URL": The URL is malformed. Provide a complete URL with protocol.

Close a browser tab by its ID, or close the currently active tab if no ID is specified. Use when the user wants to close a popup, remove an unwanted tab, or clean up after finishing work in a tab.

Parameters:

• id: Tab ID to close (omit to close the current active tab). Use pilot_tabs to list tab IDs.

Returns: Confirmation that the tab was closed.

Errors:

• "No such tab": The provided tab ID does not exist. Run pilot_tabs to see valid IDs.

• "Cannot close last tab": The last remaining tab cannot be closed.

Switch the active browser context to a specific tab by its ID. Use when the user wants to work in a different tab, bring a background tab to the foreground, or continue automation in a previously opened tab. Use pilot_tabs to find tab IDs.

Parameters:

• id: The tab ID to switch to (from pilot_tabs output)

Returns: Confirmation with the tab ID that is now active.

Errors:

• "No such tab": The provided tab ID does not exist. Run pilot_tabs to see valid IDs.

Set the browser viewport size in pixels to simulate different screen resolutions. Use when the user wants to test responsive layouts, simulate a mobile or tablet screen, or change the visible area of the page. For multi-viewport screenshots, use pilot_responsive instead.

Parameters:

• width: Viewport width in pixels (e.g., 1280 for desktop, 375 for mobile)

• height: Viewport height in pixels (e.g., 720 for desktop, 812 for mobile)

Returns: Confirmation with the new viewport dimensions.

Errors: None — any valid pixel dimensions are accepted.

Set a cookie on the current page's domain with a given name and value. Use when the user wants to manually set a cookie for authentication, testing, or session management. The cookie is set on the domain of the currently active page. For bulk cookie import from a real browser, use pilot_import_cookies.

Parameters:

• name: Cookie name (e.g., "session_id", "theme")

• value: Cookie value (e.g., "abc123", "dark")

Returns: Confirmation with the cookie name (value is redacted for security).

Errors:

• "Cannot set cookie without a page": Navigate to a URL first with pilot_navigate.

Import cookies from a real Chromium browser (Chrome, Arc, Brave, Edge, Comet) by decrypting the browser's cookie database and adding them to the headless session. Use when the user wants to transfer authentication state from their real browser, avoid re-login, access authenticated pages, or work with session cookies from an existing browser profile.

Parameters:

• browser: Browser name to import from — "chrome", "arc", "brave", "edge", or "comet". Auto-detects if omitted

• domains: Array of cookie domains to import (e.g., [".github.com", ".google.com"]). Omit to import ALL cookies (up to max_cookies)

• profile: Browser profile name to read cookies from (default: "Default"). Use list_profiles to see available profiles

• list_browsers: Set to true to list installed Chromium browsers on the system instead of importing

• list_profiles: Set to true with browser to list available profiles for that browser

• list_domains: Set to true with browser to list cookie domains available in that browser's database

Returns:

• Import mode: Count of cookies imported, per-domain breakdown, and count of any that failed to decrypt

• list_browsers mode: List of installed browser names

• list_profiles mode: List of profiles with display names

• list_domains mode: Top 50 cookie domains with counts

Errors:

• "No Chromium browsers found": No supported browsers are installed. Check the system.

• "Browser not found": The specified browser is not installed. Use list_browsers to see available options.

• "Cookie database not found": The browser's cookie file does not exist at the expected path. Check the profile name.

• Decryption failures: Some cookies may fail to decrypt (e.g., on Linux without keyring access). The count is reported.

Set a custom HTTP request header that will be sent with all subsequent requests from the browser. Use when the user wants to add an authorization header, set a custom API key, override the Accept-Language header, or inject any custom header for testing. Sensitive header values (Authorization, Cookie, X-API-Key, etc.) are auto-redacted in the response for security.

Parameters:

• name: Header name (e.g., "Authorization", "X-Custom-Header", "Accept-Language")

• value: Header value (e.g., "Bearer token123", "en-US")

Returns: Confirmation with the header name and value (sensitive values shown as "****").

Errors: None — any valid header name and value are accepted.

Set a custom browser User-Agent string, which recreates the browser context to apply the change while preserving cookies and page state. Use when the user wants to simulate a different browser or device, bypass bot detection, test mobile user agents, or debug User-Agent-dependent behavior. Note: this recreates the browser context, which may briefly interrupt in-progress requests.

Parameters:

• useragent: The full User-Agent string (e.g., "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15")

Returns: Confirmation with the new User-Agent string.

Errors:

• Context recreation warnings: If cookies or state could not be fully preserved during context recreation, a warning is included.

Configure automatic handling of native browser dialogs (alert, confirm, prompt) that would otherwise block page interaction. Use when the user wants to pre-configure dialog behavior so alerts/confirms do not pause automation, or provide a default text for prompt dialogs. Dialog messages are still captured in the dialog buffer (see pilot_dialog).

Parameters:

• accept: true to automatically accept all dialogs, false to automatically dismiss them

• prompt_text: Text to automatically enter for prompt-type dialogs (omit for empty string)

Returns: Confirmation of the configured dialog behavior.

Errors: None — this is a configuration-only call that always succeeds.

Check if the Pilot Chrome extension is connected and routing commands through the user's real browser. When connected, all navigation, snapshot, click, fill, type, scroll, screenshot, and tab commands route through Chrome — bypassing Cloudflare and bot detection.

Parameters: (none)

Returns: Connection status, port, and instructions for installing the extension if not connected.

Connect Pilot to a real Chrome browser already running on the user's machine via Chrome DevTools Protocol (CDP). Use when Cloudflare or other bot detection blocks even headed mode. A real Chrome with the user's real profile bypasses fingerprinting entirely.

Parameters:

• port (optional, default 9222): The remote debugging port Chrome was launched with.

How to start Chrome with CDP enabled: macOS: /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 Windows: "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 Linux: google-chrome --remote-debugging-port=9222

Returns: Confirmation of connection with tab count and active URL.

Errors:

• "Cannot connect": Chrome is not running or not started with the --remote-debugging-port flag.

Open a visible (headed) browser window preserving all current state — cookies, tabs, and localStorage. Use when the user is blocked by CAPTCHAs, bot detection, or complex auth flows that require manual intervention in a headed browser. After the user solves the challenge, call pilot_resume to reclaim automated control.

Parameters: (none)

Returns: Confirmation that the browser is now in headed mode with instructions to call pilot_resume when done.

Errors:

• "Browser not initialized": Call pilot_navigate first to start a browser session.

Resume automated control after a pilot_handoff session. Use when the user has finished manual interaction in the headed browser (e.g., solved a CAPTCHA, completed auth) and wants to return to automated control.

Parameters: (none)

Returns: A fresh accessibility snapshot of the current page state, ready for continued interaction.

Errors:

• "No browser to resume": No prior pilot_handoff was called or the browser has been closed.

Close the browser instance and release all associated resources. Use when the user wants to end the browsing session, clean up after completing a task, or start fresh with a new browser session.

Parameters: (none)

Returns: Confirmation that the browser was closed.

Errors:

• "No browser to close": No browser session is currently running. Safe to ignore.

Save, load, or clear browser session state (cookies + localStorage + sessionStorage) to/from a JSON file. Use when the user wants to authenticate once and reuse credentials across sessions, skip re-login flows, or transfer session state between runs. Complement to pilot_import_cookies — use pilot_auth for Pilot-managed state, pilot_import_cookies for one-time import from a real browser.

Parameters:

• action: "save" — write current session to file; "load" — restore session from file; "clear" — clear cookies and storage from browser

• path: File path to save or load (e.g., "~/.pilot/github.json"). Required for save/load actions.

Returns:

• save: Count of cookies saved and the file path.

• load: Count of cookies restored.

• clear: Confirmation that cookies and storage were cleared.

Errors:

• "Session file not found": The path does not exist. Run with action="save" first.

• "Browser not launched": Navigate to a URL first to initialize the browser.

Block network requests matching URL patterns to speed up page loads and reduce token noise from ad/tracker content. Use when the user wants to block ads, trackers, analytics scripts, or any noisy domain. Blocked requests are aborted before they hit the network — faster loads, smaller snapshots. Use the built-in "ads" preset to block ~20 major ad networks with one call.

Parameters:

• patterns: Array of URL glob patterns to block (e.g., ["googletag", ".hotjar.com/"])

• preset: Built-in preset to block — "ads" blocks ~20 major ad and tracker networks

• clear: Set to true to remove all active blocks

Returns:

• Add mode: List of active blocked patterns.

• clear mode: Confirmation that all blocks were removed.

Errors: None — invalid patterns are silently ignored by the browser.

Set or clear the browser's reported GPS coordinates to simulate a specific geographic location. Use when the user wants to test location-aware apps, see location-specific content, or simulate a user in a different country/city.

Parameters:

• latitude: Latitude in decimal degrees (e.g., 19.4326 for Mexico City, 37.7749 for San Francisco)

• longitude: Longitude in decimal degrees (e.g., -99.1332 for Mexico City, -122.4194 for San Francisco)

• accuracy: Location accuracy in meters (default: 10)

• clear: Set to true to remove the fake geolocation and revert to default behavior

Returns: Confirmation of the geolocation set or cleared.

Errors:

• "Browser not launched": Navigate to a URL first.

• Geolocation errors may occur if the page requires HTTPS for geolocation access.

List all frames (iframes) on the current page with their indices, names, and URLs. Use when the user wants to see what iframes exist on the page, find an iframe to interact with, or verify the page structure before switching frame context. The main frame is always index 0. Use pilot_frame_select to switch into an iframe.

Parameters: (none)

Returns: Numbered list of frames showing index, type ([main] or [iframe name="..."]), URL, and an arrow (→) marking the currently active frame. Returns "(no iframes — only the main frame)" if no iframes exist.

Errors: None.

Switch the browser context into an iframe so that pilot_snapshot, pilot_click, pilot_fill, and other tools operate inside that frame instead of the main page. Use when the user wants to interact with elements inside an embedded iframe, read iframe content, or fill forms within an iframe. After switching, all refs are cleared — run pilot_snapshot to get fresh refs for the iframe contents. Use pilot_frames to list available frames first.

Parameters:

• index: Frame index number from pilot_frames output (e.g., 1, 2)

• name: Frame name attribute (alternative to index)

Returns: Confirmation with the frame index/name and its URL, plus a reminder to run pilot_snapshot for fresh refs.

Errors:

• "Frame not found": The index or name does not match any frame. Run pilot_frames to see valid indices and names.

• "Provide index or name": Neither parameter was supplied.

Switch the browser context back to the main page frame after working inside an iframe. Use when the user wants to return to the main page after interacting with an iframe. All refs are cleared — run pilot_snapshot to get fresh refs for the main page content.

Parameters: (none)

Returns: Confirmation of switching to the main frame, with a reminder to run pilot_snapshot.

Errors: None — always succeeds.

Intercept network requests matching a URL pattern and respond with custom status, headers, and body. Use when the user wants to mock API responses, simulate error states (401, 500), test loading states, or run frontend tests without a real backend. All requests matching the pattern are fulfilled with the given response until cleared.

Parameters:

• pattern: URL glob pattern to intercept (e.g., "**/api/users", "/auth")

• response: Custom response — status (default 200), body (JSON string or text), headers, contentType

• clear: Set to true to remove all active intercepts

Returns:

• Add mode: Confirmation and list of active intercepts.

• clear mode: Confirmation that all intercepts were removed.

Errors:

• "Browser not launched": Navigate to a URL first.

Assert a condition about the current page state and fail with a structured error if the assertion is not met. Use when the user wants to verify the outcome of an action — that a URL was reached, text is present or absent, an element is visible/hidden/enabled, or an input has a specific value. Returns a clear pass/fail signal for agent-driven test flows.

Parameters:

• url: Assert the current page URL equals or contains this string

• text_present: Assert this text is visible somewhere on the page (waits up to 5s)

• text_absent: Assert this text is NOT visible on the page

• ref: Element ref (@eN) to assert a state or value on

• state: Expected element state — "visible", "hidden", "enabled", or "disabled"

• value: Expected input value for the element pointed to by ref

Returns: "✓ N assertion(s) passed" if all checks pass.

Errors:

• Returns isError=true with details of which assertion failed and what was found instead.

Read from or write to the browser clipboard. Use when the user wants to read content that an app copied to clipboard (share links, API keys, generated tokens), or pre-populate clipboard with text for paste operations.

Parameters:

• action: "get" — read current clipboard text; "set" — write text to clipboard

• text: Text to write when action is "set"

Returns:

• get: The current clipboard text content.

• set: Confirmation that text was written to clipboard.

Errors:

• "Clipboard read failed": Browser security policy blocked clipboard access. Try in headed mode (pilot_handoff).