browser-execute

The browser_execute tool evaluates JavaScript against a connected browser session via the Chrome DevTools Protocol. The snippet runs in-process; session is bound to a long-lived CDP Session that persists. There is no helper namespace, just session, console, and standard JS globals.

Workspace: <projectRoot>/.bcode/agent-workspace/. Read/write your reusable scripts here. Skills: {{SKILLS_DIR}}/. Read-only browser execute reference docs.

Connecting

In Browser Use Cloud API V4, browser_execute automatically connects and attaches the existing page once when the fresh run first uses this tool; do not call session.connect() or session.use() before driving it. Otherwise, call session.connect(...) once at the start of your work. There are three connection methods:

Way 1: connect to the user's running Chrome or Chromium-based browser (real profile, popup-gated).

Choose when the task involves the user's logged-in sites, current browser state, cookies, saved data, etc.

// Attempts to connect to every detected Chrome, most-recently-launched first.
await session.connect()

For this to work the user must have navigated to chrome://inspect/#remote-debugging in their target Chrome and ticked "Allow remote debugging for this browser instance". This setting is per-profile and persists across every future launch of that profile. On Chrome 144 and later, the first attach also triggers an in-browser "Allow remote debugging?" popup that the user must click "Allow" on. The popup may reappear on later attaches under conditions that are not fully characterized — browser restart, time elapsed, new CDP session. Ask the user to click Allow again if a previously working connection starts 403'ing.

Failure modes:

• connect() throws "No running browser with remote debugging detected". The checkbox at chrome://inspect/#remote-debugging has not been ticked in any running Chrome profile, or no Chrome is running.
• connect() throws with "403" / "permission" / "WS closed before open". The checkbox is ticked but the user hasn't clicked Allow on the popup yet. By default connect() errors in 5s; pass { timeoutMs: 30000 } to wait up to 30s for the click.

Way 2: connect to a Chrome or Chromium-based browser launched with a debug port (isolated profile, no popups).

Choose for unattended automation, or for an isolated browser.

Launch Chrome with --remote-debugging-port=<port> --user-data-dir=<path>. Pick a directory you can access — e.g., a project-local one like ./.bcode/chrome-data-dir.

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=./.bcode/chrome-data-dir
# macOS
"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 --user-data-dir=./.bcode/chrome-data-dir
# Windows (cmd.exe)
"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --remote-debugging-port=9222 --user-data-dir=.\.bcode\chrome-data-dir
# Windows (PowerShell)
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 --user-data-dir=.\.bcode\chrome-data-dir

// Resolve the live WebSocket URL via `/json/version` and connect:
const ver = await fetch("http://127.0.0.1:9222/json/version").then(r => r.json())
await session.connect({ wsUrl: ver.webSocketDebuggerUrl })

--user-data-dir must not be Chrome's platform default. Chrome 136 and later silently no-ops the --remote-debugging-port flag when --user-data-dir is the platform default. The platform defaults are %LOCALAPPDATA%\Google\Chrome\User Data on Windows, ~/Library/Application Support/Google/Chrome on macOS, ~/.config/google-chrome on Linux. You cannot reuse the user's everyday Chrome profile by copying its files into a custom directory.

Failure modes:

• Chrome's launch log prints DevTools listening on ws://...:<port>/... immediately followed by bind() failed: Address already in use and Chrome exits. Confirm the port is actually open with curl http://127.0.0.1:<port>/json/version before connecting.
• { profileDir } raises ENOENT on DevToolsActivePort. Chrome 147+ doesn't write this file under custom --user-data-dir; use the /json/version route above instead.
• Launch silently no-ops --remote-debugging-port. Launching a second Chrome that points at a --user-data-dir matching a running process ignores --remote-debugging-port.