Navigate to URL or go forward/back. Omit tabId for new tab.

Mouse, keyboard, and screenshot actions on a tab. Supports click, type, scroll, key, hover, and screenshot by pixel coordinate or element ref.

When to use: Precise coordinate-based input, screenshots, or keyboard shortcuts. When NOT to use: Use interact for natural-language element actions, or act for multi-step sequences.

Get page as DOM, accessibility tree (ax), CSS diagnostics, semantic summary, or clean Markdown (article-shaped).

When to use: Reading page structure, verifying content, extracting the full DOM tree, or reducing article-like pages to Markdown. When NOT to use: Use inspect for targeted state queries or find to locate a specific element.

Find elements by query. Returns up to 20 matches with refs.

When to use: Locating elements by natural language when exact selectors are unknown. When NOT to use: Use query_dom when you have a CSS selector or XPath, or interact to find-and-click in one step.

Set one form element value by ref. Pass intent="..." (≤120 chars) to label this action in audit logs.

When to use: Filling a single known input, textarea, select, or checkbox by ref. When NOT to use: Use fill_form({fields:{...}}) for multiple fields or optional submit.

Execute JavaScript in page context. Supports await, async IIFE, and shadow-DOM helpers via __pierce.

When to use: Custom DOM queries, data extraction, or triggering JS APIs not reachable via other tools. When NOT to use: Use interact or act for UI interactions, or extract_data for structured schema-based extraction.

Simulate network conditions.

Reload the current page.

Manage browser cookies (get, set, delete, clear).

Query DOM elements via CSS selector or XPath. Returns tag, attributes, text, position. CSS results include a ref field for use in subsequent calls.

When to use: Precise element lookup by CSS selector or XPath when you know the exact selector. When NOT to use: Use find for natural-language element search or read_page for full DOM structure.

Get HTML content from page or element.

Wait for a condition. Strongly prefer 'function', 'selector', or 'url_match' — they return as soon as the condition is true (1 round-trip). Use 'timeout' only as a last resort: it blocks for a fixed duration and returns no information, forcing you to poll with another tool afterwards.

Manage browser localStorage and sessionStorage.

Set or reset browser user agent.

Set or clear geolocation override.

Emulate device viewport and UA via preset or custom.

Generate PDF from page. Saves to path or returns base64.

Save page screenshot to file or return as base64. Supports full-page capture, region clipping, and multiple image formats.

When to use: Capturing a screenshot for saving to disk or when the full-page or clipped region is needed. When NOT to use: Use computer(action:"screenshot") for an inline viewport screenshot during interaction.

Capture browser console output (start, stop, get, clear).

Get page performance metrics.

Intercept network requests (log, block, modify). preset="optimize-bandwidth" blocks Image/Media/Font/Stylesheet; preset="optimize-bandwidth-light" blocks Image/Media/Font. User block/allow/modify rules run after presets; explicit allow rules win. OPENCHROME_OPTIMIZE_BANDWIDTH= can auto-apply to new targets.

Capture network request metadata + headers (no bodies). Cheap passive recorder. Actions: start, stop, getLogs, clear.

Capture network requests with response bodies (capped). Actions: start, stop, getLogs, clear. Bodies over maxBodyBytes are omitted with reason="over_cap".

Upload files to a file input element on the page. Pass intent="..." (≤120 chars) to label this action in audit logs.

Set or clear HTTP auth credentials.

Drag and drop by selector or coordinates. Pass intent="..." (≤120 chars) to label this action in audit logs.

Fill form fields and optionally submit. Pass intent="..." (≤120 chars) to label this action in audit logs.

Get session tab IDs grouped by worker.

Create a new tab with URL.

Close one or more tabs by tabId, tabIds, or workerId.

Manage workers. Actions: "create" (isolated context), "list" (show all), "delete" (remove and close tabs).

Initialize a workflow with multiple isolated workers for parallel browser ops.

Get current workflow status and worker states.

Collect and aggregate results from all workers after completion.

Collect results from completed workers without waiting for all to finish.

Clean up workflow resources (workers, tabs, scratchpads).

Report worker progress to the orchestration scratchpad.

Mark a worker as complete with final results.

Execute a cached plan by ID, bypassing per-step LLM calls. Falls back gracefully on failure for manual retry.

Execute JS across multiple tabs in parallel.

Scroll page via JS. Returns new scroll position.

Extract content from paginated viewers in one call.

Find element by natural language; click/hover/double_click it; wait for DOM settle; return state.

When to use: One described element action, with coordinate fallback for Shadow DOM/canvas/iframes. When NOT to use: Use act for multi-step flows; computer for general coordinate clicks.

Extract focused page state by query. Returns headings, form fields, errors, tabs, and interactive counts scoped to the query intent.

When to use: Checking focused aspects of page state (forms, errors, tabs) without loading the full DOM. When NOT to use: Use read_page for full DOM/AX tree, or find to locate a specific element.

Find elements using vision-based screenshot analysis. Returns annotated screenshot with numbered elements.

Manage domain knowledge. Actions: "record" (store), "query" (retrieve by domain), "validate" (adjust confidence). Key prefixes: "selector:", "tip:", "avoid:".

Resolve a semantic element query into stable refs for interaction workflows. Uses local AX/DOM matching only; no external AgentQL or LLM provider is called. Pass returned refs to interact, act, fill_form, read_page(ref_id), or plan parseResult.storeAs paths.

Shut down OpenChrome and close Chrome. Auto-relaunched on next tool call.

Manually sweep and terminate orphaned OpenChrome-managed Chrome processes. Never touches attach-mode or unmarked user Chrome.

Check browser profile type and capabilities.

List available Chrome profiles with names and directory IDs.

Save browser state snapshot for context recovery after compaction. Captures open tabs, worker state, and your task memo. Use before long operations or periodically during multi-step tasks. Restore with oc_session_resume.

Restore working context after context compaction. Reads the last oc_session_snapshot, checks which tabs are still alive, and returns a resume guide with your objective, progress, and tab status. Call this after compaction to continue where you left off.

Query the tool call journal. Actions: "summary" (milestone overview), "recent" (last N entries), "handoff_summary" (compact JSON resume handoff). When to use: Reviewing session history, restoring context, or auditing past tool calls. When NOT to use: Use read_page or inspect to check the current live page state.

Create, get, or list structured task-failure reflection artifacts. Reflections are passive recovery guidance only; OpenChrome never executes nextPlan automatically.

Get CDP connection health metrics including heartbeat mode, reconnect count, ping latency, connection state, and live reconnection progress. Use this to monitor connection stability during long-running sessions.

Inspect deterministic OpenChrome safety policy. Use action="matrix" to list irreversible-action rules or action="evaluate" to preview a policy decision for a tool/args context.

Save, load, list, or delete automation checkpoints for long-running session continuity. Use "save" to persist current task state, "list" to inspect the bounded checkpoint timeline, "load" to restore metadata after context compaction, and "delete" to clean up.

Get connection configuration for a web AI host (Claude Web, ChatGPT, Gemini, or custom). Returns the MCP server URL, bearer token, settings page URL, step-by-step instructions, and (when Chrome is reachable) a devtools block with live DevTools inspector URLs for all open pages. Use host="openchrome" to introspect the openchrome server itself — when --auto-connect is active, returns {mode: "auto-connect", userDataDir, port}.

Copy text to the system clipboard. Useful for copying MCP server URLs or config snippets.

Open the MCP connector settings page for a web AI host in the default browser.

Start a new session recording. All subsequent MCP tool calls will be recorded until oc_recording_stop is called. Errors if a recording is already active.

Stop the active session recording and finalize it to disk. Returns a summary of the recording. Errors if no recording is active.

Report whether session recording is active, including trajectory bundle metadata when enabled.

List available session recordings, newest first.

Export a recording as JSON or a self-contained HTML report. For HTML, saves to ~/.openchrome/recordings/{id}/report.html and returns the path.

Recursively crawl a website via BFS. Opens pages in new tabs, extracts text and links, follows them up to max_depth. Respects robots.txt and scope constraints.

When to use: Extracting content from multiple pages of a site when the URL structure is not known in advance. When NOT to use: Use crawl_sitemap when the site has a sitemap.xml, or navigate for a single page.

Crawl a website using its sitemap.xml. Auto-discovers sitemaps from robots.txt or /sitemap.xml. Supports sitemap index files and URL filtering.

When to use: Extracting content from many pages of a site that publishes a sitemap.xml. When NOT to use: Use crawl for BFS discovery when no sitemap exists, or navigate for a single page.

Initialise a resumable crawl job. Returns { jobId, status: "pending" } immediately — performs NO network I/O. Drive progress with crawl_status({ jobId, advance: N }) which fetches up to N pages per call. Same args as the legacy crawl tool. Use crawl_cancel to stop.

Advance a crawl job by up to advance pages (default 5, env OC_CRAWL_ADVANCE_DEFAULT) and return current state. advance: 0 is read-only and performs no fetching. Returns { status, completed, total, errors, pages?, pagesOmitted?, startedAt, finishedAt? }. Pages array is capped at OC_CRAWL_STATUS_MAX_PAGES (default 200).

Mark a crawl job as cancelled. Returns immediately. Subsequent crawl_status calls on this jobId will skip the runner and report status "cancelled".

Execute multi-step browser actions from a natural language instruction. Parses and runs click, type, select, scroll, hover, navigate, and wait steps in sequence.

When to use: Automating a known multi-step flow (login, form fill, navigation) in one call. When NOT to use: Use interact for a single element action, or computer for raw coordinate input.

Composite health check: navigate, wait, capture console errors, return structured summary (title, errors, interactive count, body sample).

When to use: Verifying a page renders correctly without errors in a single call instead of chaining navigate + wait_for + console_capture + read_page. When NOT to use: Use navigate + read_page when you need full DOM content, not just a health summary.

Extract JSON-schema data from JSON-LD, Microdata, OpenGraph, or CSS. Use multiple:true for listings, mode="semantic" plus query for bounded host-side chunks, or exactly one scope: selector, ref_id, backendNodeId.

When to use: Typed products, articles, prices, or semantic facts. When NOT to use: Use read_page for raw content or javascript_tool for ad-hoc scraping.

Generate a current TOTP 2FA code for a domain. Requires TOTP secret to be configured.

Evaluate a single Outcome Contract assertion against caller-supplied evidence (snapshot). Returns verdict pass/fail/inconclusive plus the list of failed leaf assertions. Core-tier single-call surface; retry and escalation live in the pilot runtime.

Compress a sliding window of journal entries into a compact model-friendly summary. Defaults to a deterministic recent_k strategy that fits a token budget. checkpoint_only returns milestone-flagged entries. sampling forwards a summarisation prompt to the host LLM via sampling/createMessage — only available when the client advertises the sampling capability; returns { status: "unsupported_by_host" } otherwise. OpenChrome never uses its own LLM.

Ask the connected host LLM a question about a caller-supplied screenshot. Forwards via MCP sampling/createMessage when the client advertises the sampling capability. Returns { status: "unsupported_by_host", reason } when the capability is absent — OpenChrome never uses its own API keys. The caller MUST supply one of screenshot.ref, screenshot.path, or screenshot.base64. No auto-capture.

Detect whether the current tab is gated (CAPTCHA, bot-check, SSO redirect, paywall, 2FA prompt). Returns facts only — never invokes any solver, never makes a third-party HTTP call, never bypasses the gate. The host agent decides what to do next.

Validate and normalize a near-valid browser/computer action payload without executing it. Use this before calling real action tools when a host model produced aliases such as left_click, hotkey, coordinate, or missing click button. This tool is side-effect-free: it does not touch Chrome, CDP, tabs, DOM, cookies, storage, or files.

Read-only diagnostics for whether the current OpenChrome session appears to be progressing, stalling, or stuck. Returns bounded counters and advisory next-call suggestions; it never stops, retries, recovers, or executes browser actions.

Collect a read-only Web Vitals snapshot from the current page without adding page scripts or package dependencies. Returns LCP, CLS, INP, TTFB, and FCP with Core Web Vitals ratings where browser timing entries are available.

Redeem an output handle returned by a large-output tool (read_page, crawl, network, extract_data, oc_evidence_bundle). Supports offset/limit pagination for JSON arrays (item-based) and binary blobs (byte-range). Returns eof=true and next_offset=null when the last page has been read.

Capture a snapshot of the current page state (DOM, screenshot, network slice, console, perceptual hash) and write it to a bundle directory. Returns { bundle_id, path, size_bytes, parts }. Default include = ['dom', 'screenshot']; pass include to capture more parts. network_window_ms (default 5000) limits the network slice to recent entries. Core-tier; does not depend on the pilot runtime.

Compare two evidence-bundle IDs or paths and return deterministic DOM, screenshot phash, URL, console, and network diff facts.

Record a skill (domain, name, steps, contract_id) into the JSON skill memory store. Idempotent on (domain, name) — re-recording preserves the existing skill_id and usage counters while updating steps and contract_id. Pass frozen_snapshot to atomically write a gzipped snapshot alongside the record. Returns { skill_id, stored_at, snapshot_path? }. Core-tier; no LLM ranking. Use oc_skill_recall to retrieve skills.

Retrieve skills from the JSON skill memory store for a given domain. Returns a recency-sorted list (last_used_at desc). Optionally filter by contract_id and cap results with limit (default 20). No LLM ranking — deterministic store order is returned as-is unless task/query or ranked is supplied. Each result carries codegenReplay ({available, artifacts}) for the LLM-free replay fast path. Use oc_skill_record to write skills.

Export an opt-in codegen replay artifact written by --codegen. Returns the path and byte count for puppeteer, playwright, or mcp-replay output. Default OpenChrome behavior is unchanged when --codegen is off.

Create a task-level browser harness envelope, or launch a long-running tool as a background task. Returns a task_id that can be polled with oc_task_get / oc_task_list / oc_task_wait, or aborted with oc_task_cancel. The result is persisted to disk and survives MCP-session loss.

List background tasks in the ledger. Default limit=50, sorted by created_at descending. Supports status/kind/since/limit filters.

Fetch a single task by task_id. By default returns meta only; pass include_result=true to also resolve the persisted result payload.

Request cancellation of a background task. Best-effort: the runner aborts the underlying tool at the next work-unit boundary. Terminal tasks are unaffected. PENDING tasks transition straight to CANCELLED.

Block until the task reaches a terminal state (COMPLETED / FAILED / CANCELLED) or timeout_ms elapses. Default timeout_ms is 60000.

Update a task envelope phase or note. Does not execute browser actions.

Finish a host-driven task envelope as completed, failed, or cancelled.

Create a task-scoped browser lane on existing SessionManager worker/target primitives. Lanes isolate refs, tabs, and trace metadata for host-driven parallel work. Optional profile: "inherit" (default) shares the server Chrome user-data-dir; "scratch" provisions a fresh temp user-data-dir at creation and removes it on oc_lane_close.

List task-scoped browser lanes for a task.

Fetch one task-scoped browser lane including live target ids and counters.

Close a task-scoped browser lane and its lane-owned targets without closing unrelated task tabs.

Read the most recent openchrome doctor diagnostic report from cache. Returns the DoctorReport written by the last openchrome doctor run. Does NOT trigger new checks — run openchrome doctor in a shell to refresh.