Drive a browser

Bind a browser window, snapshot its tab, and navigate, click, and type without raising it; attach to a logged-in Chrome or Edge profile.

The browser_* tools act inside Chromium and Electron pages through the Chrome DevTools Protocol (CDP), bound to the exact native window you picked. They reach an occluded tab without moving the real cursor or taking keyboard focus. Safari, Firefox, Tauri, WKWebView, WebKitGTK, and split-process WebView2 hosts return browser_route_unavailable; use the native accessibility and pixel actions there.

Chrome remains behind the agent terminal

Claude Code starts a YouTube video in Chrome without raising the browser window.

View the original post on X

Bind and snapshot#

Browser capabilities belong to a named session. Pick the window with list_apps and list_windows, then bind it:

start_session({"session": "research-1"})
get_browser_state({"pid": 844, "window_id": 10725, "session": "research-1"})

Keep the returned opaque target_id and the tab_id whose active is true. active: null means the window title cannot tell tabs apart: choose a tab explicitly. Mutation needs binding_quality: "exact".

Snapshot the tab, then act only on returned refs:

get_browser_state({
  "target_id": "<target_id>", "tab_id": "<tab_id>",
  "session": "research-1", "snapshot_format": "semantic_v2"
})

A semantic_v2 snapshot returns an outline of visible content, action refs (each lists click, type, upload, or pointer in actions), and read-only content_refs for scope_ref. Narrow it with query or scope_ref; follow snapshot.continuation for the next segment. Refs die on a newer snapshot, navigation, or reconnect: snapshot again after browser_ref_stale.

Act#

browser_click({"target_id": "<target_id>", "tab_id": "<tab_id>", "ref": "p1:7", "session": "research-1"})
browser_type({"target_id": "<target_id>", "tab_id": "<tab_id>", "ref": "p2:3", "text": "status: ready", "replace": true, "session": "research-1"})
browser_navigate({"target_id": "<target_id>", "tab_id": "<tab_id>", "url": "https://example.com", "session": "research-1"})
end_session({"session": "research-1"})
ToolNotes
browser_clickTrusted CDP input by default. Works fully in the background for Chrome and Edge on Windows and Chrome on macOS, including inactive tabs; Linux returns browser_input_trust_unavailable because the browser would activate. Pass input_route: "dom_event" for a synthetic pointer, mouse and click sequence that stays in the background but returns effect: "unverifiable".
browser_typeinsert_text by default; mode: "keystrokes" for per-key events; replace: true to overwrite.
browser_pointerhover, right_click, double_click, scroll, drag (with destination_ref in the same frame).
browser_dialoginspect, then accept or dismiss the returned dialog_id. Linux needs delivery_mode: "foreground".
browser_set_input_filesAbsolute paths to regular files (max 32), on a ref with upload.
browser_downloadInto an existing absolute destination_root that your policy admits. Returns only a byte count and id.
browser_navigateInvalidates every ref on the tab.

Verify the result with a fresh snapshot. The driver never falls back from trusted input to a DOM event, or foregrounds the browser, to make a call look successful.

Use an isolated browser#

When get_browser_state returns browser_requires_setup, start a separate driver-owned Chromium profile. It never touches the person's profile:

browser_prepare({
  "pid": 844, "session": "research-1", "allow_launch": true,
  "profile": {"mode": "isolated_new"}
})

Bind the window of the returned prepared_pid. An isolated_new profile is deleted when the session ends; use {"mode": "isolated_named", "name": "research"} to keep it. Do not pass remote-debugging flags through launch_app: they are refused.

An isolated browser keeps its passwords and cookies away from the system keychain (on macOS it starts with --use-mock-keychain, on Linux with --password-store=basic), so launching one never shows a Keychain prompt. If a Keychain or password prompt is already on screen, or one appears while the browser starts, browser_prepare stops with browser_route_unavailable (detail.reason is security_prompt_open or security_prompt_appeared) instead of launching more browsers. The driver never answers these prompts; ask the person to close it. After three failed launches in a row, further launches are refused for a back-off that starts at 30 seconds (detail.reason is isolated_launch_backoff, with retry_after_seconds). Fix the cause before retrying.

The result's optional lifecycle object describes how long the browser process lives: owner is session, idle_expires_in_seconds is how long the session may stay idle after this call before it and the browser end, process_ends_with_session is true, and profile_persists_after_session is true only for isolated_named. The value is advisory, not a lease. get_session reports the remaining time later but does not keep the browser alive, and explicit end_session, disconnect, revocation, or shutdown ends the browser earlier. A named profile keeps its files, not the process or its open pages. Attachments to an existing profile or endpoint the driver did not launch, and sessions already ending, have no lifecycle.

Attach to a logged-in profile#

Use an existing Chrome or Edge profile only when the task needs its signed-in session, on a trusted machine. CDP exposes that profile's pages, cookies, and storage, and loopback is not authentication: other processes running as the same user can reach an open endpoint.

Relaunching the browser yourself with --remote-debugging-port does not reach that profile. Chrome and Edge ignore the flag on their default user-data directory: no listener opens and no DevToolsActivePort file is written. The flag works only with a different --user-data-dir, which is a different, signed-out profile. The browser's own remote-debugging switch, which browser_prepare drives below, is the route into the real profile.

Attachment is an explicit boundary. It needs --grant existing-profile at launch (standard), a manifest entry kind: existing_profile (bounded), an embedding host's authorization callback, or unrestricted mode. A tool argument or MCP approval cannot grant it.

A bounded manifest for this (on Windows and Linux, use Chrome's absolute executable path instead of bundle_id):

version: 3
expires_after: 2h
idle_timeout: 20m
 
resources:
  apps:
    - bundle_id: com.google.Chrome
      launch: false
      windows: all
      terminate: deny
  browser:
    profiles:
      - kind: existing_profile
    origins:
      - https://app.example.com
 
allow:
  tools:
    - start_session
    - end_session
    - get_browser_state
    - browser_prepare
    - browser_navigate
    - browser_click
    - browser_type
cua-driver serve \
  --permission-mode bounded \
  --capability-manifest ./browser-session.yaml \
  --approve-capability-manifest

For a standalone standard-mode launch instead, use cua-driver mcp --grant existing-profile or cua-driver serve --grant existing-profile. Then request the exact window:

browser_prepare({
  "pid": 844, "window_id": 10725, "session": "research-1",
  "strategy": {"kind": "existing_profile"}
})

If the browser has no DevTools endpoint, the driver opens a temporary tab at chrome://inspect/#remote-debugging (or edge://…), turns on Allow remote debugging for this browser instance, proves the new listener is loopback and owned by that process, and closes the tab. It presses only the browser's own consent button. On Chrome 144 and later it connects through the running profile's auto-connect endpoint. It never restarts, copies, or edits the profile. The result's side_effects reports what it did (for example enabled_remote_debugging, foregrounded_window). On macOS, if Chrome hides that page's accessibility tree, a bounded pixel click on the setup page may briefly foreground the approved window and then restore focus.

After attached_existing_profile, bind again with get_browser_state; old ids are invalid. The grant lives in memory: it expires after 30 minutes idle or 8 hours, and ends with the session or runtime. Ending the session does not turn off Chrome's remote-debugging setting; do that in Chrome.

Supported: Chrome and Edge on macOS, Windows, and Linux X11; Chrome on GNOME Wayland; Chrome, Edge, and Chromium on Sway. On Linux, start the browser with --force-renderer-accessibility. Setup recognizes English UI labels only.

On macOS 27 and later, reading the Chrome and Edge profile folders needs Full Disk Access or a per-app grant, so attachment through the daemon refuses with browser_route_unavailable until CuaDriver.app has that access. Grant it Full Disk Access in System Settings, then restart the daemon. A runtime started with cua-driver mcp --direct reads the folder with its host app's access instead.

Refusals#

CodeMeaning
browser_requires_setupNo approved endpoint: call browser_prepare.
browser_consent_requiredExisting profile without a grant, host approval, or matching manifest.
browser_consent_revokedThe host denied, or the browser's prompt was dismissed.
browser_ref_stale, browser_binding_staleSnapshot or bind again.
browser_wrong_target_refused, browser_endpoint_owner_mismatchWindow, prompt, or endpoint identity is not exact.
browser_input_trust_unavailableTrusted input would activate the browser; use input_route: "dom_event" if acceptable.
browser_route_unavailableNo typed route for this engine or platform.
browser_origin_outside_scopeThe tab left the manifest's origins; mutation pauses.
browser_action_unavailableThe ref does not declare the needed action.

The legacy page tool keeps its read-only get_text and query_dom actions, which are the way to read Safari and Firefox pages. Its page actions (run JavaScript, click, type) and the CUA_DRIVER_ENABLE_LEGACY_PAGE_MUTATIONS switch were removed; act on a page with the typed browser_* tools.