brow-use
← Architecture

Session mode

Automate your real Chrome session — logged-in state, cookies, real profile.

The problem it solves

By default, brow-use launches a fresh Chromium instance managed by Playwright. That browser has no cookies, no saved credentials, and no extensions. Every run starts from a blank slate. For publicly accessible pages this is fine. For anything behind a login it means re-authenticating on every run — or building a login workflow before you can test anything else.

Session mode solves this by routing automation through your real Chrome browser via the brow-use extension and playwright-crx. The extension attaches Playwright to your existing tab using chrome.debugger. You are already logged in. Cookies, storage, and profile state are all present. The agent operates on the same browser you use every day.

Mode comparison

Capability Mode 1 — default Mode 2 — session
Browser Fresh Chromium launched by Playwright Your real Chrome with your profile
Login state None — must authenticate each run Present — already logged in
Cookies & storage Empty Your real session data
Trace fidelity Full — action attribution, DOM snapshots, network Full — same format, same viewer
Accessibility tree Full Full
Visible indicator Separate browser window appears Yellow "DevTools is debugging" banner

The agent harness, MCP tools, and output format are identical in both modes. The only difference is where the automation runs and what session state is available.

How it works

The MCP server runs a WebSocket server on port 3456. The brow-use Chrome extension connects to it as a client. When session mode is active, browser tool calls are routed to the extension over this WebSocket rather than to a Playwright-controlled browser.

Inside the extension, playwright-crx provides a full Playwright API backed by chrome.debugger instead of the normal Playwright transport. The extension executes each command — click, type, navigate, accessibility tree, screenshot, trace start/stop — on the active Chrome tab and returns the result over WebSocket.

File-writing tools (write_page_object, write_workflow, write_test) always run on the Node.js side regardless of mode.

Setup

1 — Build the extension

npm run build

This builds both the MCP server (dist/mcp/) and the extension (dist/extension/) in a single step.

2 — Load the extension in Chrome

  1. Open chrome://extensions
  2. Enable Developer mode (toggle, top-right)
  3. Click Load unpacked and select the dist/extension/ directory
  4. The brow-use icon appears in the toolbar. Click it — it should show "Connected to brow-use server" once the MCP server is running.
The extension only needs to be loaded once. After that it reconnects automatically each time the MCP server starts.

3 — Switch to session mode

Run the skill from Claude Code:

/bu:use-session

Or call the tool directly:

set_mode({ mode: "crx" })

To return to the default Playwright mode:

set_mode({ mode: "playwright" })
Mode is per-session. It resets to playwright each time the MCP server restarts.

Tracing in session mode

Traces captured in session mode are identical in format to Mode 1 traces — full action attribution, DOM snapshots at every step, network activity, and screenshots. The trace file is written to output/trace/ and is compatible with npx playwright show-trace.

The difference: the extension captures the trace internally using playwright-crx, then sends the .zip bytes back to the Node.js server over WebSocket, which writes the file to disk. The result is indistinguishable from a Mode 1 trace. 

npx playwright show-trace output/trace/<name>-<timestamp>.zip

Notes