browser-bridge

<p align="center"> <img src="docs/banner.svg" alt="Browser Bridge - drive your real, logged-in Chrome from an AI agent" width="860"> </p> <p align="center"> <em>Drive your real, logged-in Chrome from an AI agent - over the Model Context Protocol.</em><br> _{No headless browser. No fresh profile. No re-login. Your agent reads and acts inside the exact sessions you're already signed into.} </p> <p align="center"> <img alt="version" src="https://img.shields.io/badge/version-0.16.0-3f3f46?style=flat-square"> <img alt="tools" src="https://img.shields.io/badge/tools-68-3f3f46?style=flat-square"> <img alt="protocol" src="https://img.shields.io/badge/MCP-streamable_HTTP-52525b?style=flat-square"> <img alt="browser" src="https://img.shields.io/badge/Chrome%2FEdge-Manifest_V3-52525b?style=flat-square"> <img alt="language" src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square"> <a href="LICENSE"><img alt="license" src="https://img.shields.io/badge/license-MIT-16a34a?style=flat-square"></a> <a href="CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-16a34a?style=flat-square"></a> </p>

Browser Bridge is a local MCP server + Manifest V3 Chrome extension that lets AI coding agents - Claude Code and OpenAI Codex CLI - control the Chrome you use every day. Because it runs inside your real profile, the agent inherits your cookies, HttpOnly sessions, SSO, and 2FA state automatically. Ask it to "read my feed and summarize it" or "capture the API traffic on this page and show me the responses" - and it works against the live, authenticated app.

It ships 68 tools spanning everyday browsing, DevTools-grade network capture, a full web-security testing toolkit, playbooks (saved, self-healing recipes), session recording - record an interaction into a self-contained, offline-faithful HTML replay (full-page, custom-designed player, with a smooth mouse-trail / click / keystroke overlay) and export it to a high-resolution MP4 - and watch mode, which runs the whole thing in reverse: you browse, and the agent reads a live, labeled timeline of what you did and what the page sent.

<p align="center"> <img src="docs/replay.gif" alt="Session replay: a recorded interaction played back in the self-contained FRACTURE player - a smooth green mouse trail follows the cursor, click ripples fire, and a keystroke HUD shows what was typed, with a play/scrub timeline and speed controls" width="820"> <br> _{<em>Record a session → a self-contained, offline replay with a smooth mouse-trail / click / keystroke overlay → export to a high-res MP4.</em>} </p>

Contents

• Quick start
• Why Browser Bridge?
• See it in action
• Architecture
• Features & tools
• Playbooks
• Recording
• Watch mode
• Setup
• Security & responsible use
• Limitations
• Roadmap
• Contributing
• License

Quick start

Build both packages, run the server, load the extension, connect your agent - about 60 seconds:

git clone https://github.com/vitalysim/browser-bridge.git && cd browser-bridge
( cd server    && npm install && npm run build )   # MCP server (TypeScript → dist/)
( cd extension && npm install && npm run build )   # bundles background.js + options.js
( cd server    && npm run install-service )        # run the server at login (systemd/launchd)

1. Load the extension - open chrome://extensions, enable Developer mode, click Load unpacked, select the extension/ folder, then open its options and paste the token from ~/.browser-bridge/token → Save & connect.

2. Connect your agent:

   Claude Code

   claude mcp add --transport http --scope user browser-bridge \
     http://127.0.0.1:8765/mcp --header "Authorization: Bearer $(cat ~/.browser-bridge/token)"
   

   OpenAI Codex CLI - export the token so Codex can read it, then register the server in one command:

   export BROWSER_BRIDGE_TOKEN="$(cat "$HOME/.browser-bridge/token")"   # add to your shell profile
   codex mcp add browser-bridge --url http://127.0.0.1:8765/mcp --bearer-token-env-var BROWSER_BRIDGE_TOKEN
   

Verify: curl -s http://127.0.0.1:8765/health → {"ok":true,"extensionConnected":true}. Full details, autostart options, and the manual config alternatives are in Setup.

Why Browser Bridge?

| | Browser Bridge | Headless Playwright / Puppeteer | A raw CDP debug port | |---|:---:|:---:|:---:| | Uses your real logged-in profile | ✅ | ❌ (fresh profile, re-login) | ⚠️ blocked on default profile since Chrome 136 | | Works from Claude Code and Codex | ✅ | - | - | | No open debug port on your session | ✅ (outbound WS) | n/a | ❌ any local process can hijack it | | DevTools-grade capture (bodies, WS) | ✅ | partial | ✅ | | One-command install, no native host | ✅ | ✅ | ✅ |

• One server, two clients. Both agents connect to the same token-authed endpoint http://127.0.0.1:8765/mcp. Anthropic's Claude in Chrome is Claude-only and OpenAI's Codex browser extension is desktop-app-only - neither gives the Codex CLI a real browser. Browser Bridge does.
• Extension, not a debug port. Chrome 136+ blocks --remote-debugging-port on your default profile. A Manifest V3 extension runs inside that profile instead - banner-free by default, with chrome.debugger (CDP) power features attached only on demand.
• Outbound WebSocket, no native-messaging host. The extension dials ws://127.0.0.1:8765/ws; there are no host-manifest files to install, and the WS keepalive keeps the MV3 service worker alive.
• Localhost-only + token auth. The server binds 127.0.0.1, checks a bearer token on both the MCP endpoint and the WS handshake, and rejects any WS origin that isn't chrome-extension://.

See it in action

With Chrome open and logged in, just ask your agent in natural language:

# Everyday
list my open tabs
open github.com, read my notifications, and summarize them

# Screenshots
take a full-page retina screenshot of this page and save it to ~/Downloads/page.png

# Network capture
start a network capture on this tab, reload it, and show me the JSON API responses

# Record & export
record my session, I'll click around and type, then stop - build the HTML replay and a 2x MP4

# Web-security (authorized targets only)
capture identity "A" for app.example.com, then log in as B and capture "B";
replay the invoices request as A, B and anon and show me the authz_matrix

# Remote desktop / canvas (e.g. a CTF AttackBox)
screenshot the DCV desktop, click the terminal, type "id" and press Enter, then screenshot the output

# Watch mode - you drive, the agent follows
watch what I do on this site, with network capture
...browse normally...
what did I just do? what did that "Publish" click actually send?

Both Claude Code and Codex drive the same live browser through the same endpoint.

Architecture

<p align="center"> <img src="docs/architecture.svg" alt="Architecture - Claude Code and Codex CLI connect over streamable-HTTP MCP to the bridge server, which relays over an outbound token-authed WebSocket to the Chrome MV3 extension, which drives your real logged-in tabs" width="560"> </p>

Features & tools

• Batch multi-step work - browser_batch runs a predictable sequence (navigate → click → fill → press_key → screenshot) in one round trip instead of five. The per-call round trip, not the browser, is what makes multi-step tasks slow, so this is the single largest speedup available.
• Browse & interact - tabs, navigation, and click / fill / hover / type / scroll with auto-wait actionability (found + visible + enabled, auto-escalating to a trusted CDP click when a target is overlay-covered), plus file and image upload - all reaching into iframes (incl. cross-origin) and open shadow DOM - and coordinate-level trusted input (input) for <canvas> remote desktops (VNC/RDP/Amazon DCV), games, and drawing apps.
• Read & inspect - rendered page text, interactive-element snapshots with stable refs, screenshots (viewport → full-page retina, element clip, save-to-disk), and JavaScript evaluation that bypasses strict CSP via CDP.
• DevTools-grade capture - full request/response bodies, response headers, Set-Cookie, timings, and WebSocket/SSE frames - with durable on-disk persistence and HAR / MHTML evidence export.
• Web-security toolkit - named identities, an in-session request replayer, BOLA/IDOR/BFLA access-control diffing (authz_matrix), Burp-style live interception, an intruder-style fuzzer (sniper/pitchfork/clusterbomb/race), passive header/CORS/secret analysis, JWT decode, and copy-as-curl.
• Session & storage - read/write the real cookie jar (incl. HttpOnly), localStorage / sessionStorage, and console + CSP + exception logs.
• Watch mode (copilot) - the inverse of everything above: you browse and the agent follows along. A content script emits already-labeled events (click <button#publish> "Publish", typed text, SPA route changes) into a cursor-addressable timeline you read with watch_read({since}) - with requests and console errors folded in and attributed to the action that caused them.

<details open> <summary><b>Browsing &amp; interaction</b></summary>

| Tool | Description | |---|---| | tabs_list · tab_new · tab_activate · tab_close | Manage tabs. tabs_list(short:true) returns id/title/origin/active only (no path/query), for quickly identifying tabs without echoing full URLs | | navigate · go_back · go_forward · wait_for | Navigation | | click · fill · hover · type · press_key · scroll | Interaction (iframe + open-shadow aware). Auto-waits for the element to be actionable (found + visible + enabled, timeoutMs) and returns structured {notActionable, reason} on failure. click detects overlay-covered targets and auto-escalates to a trusted CDP click (via:"trusted"); fill/type register in React inputs (native setter) and rich editors (execCommand). trusted:true for real CDP input; withSnapshot:true to get a fresh snapshot back inline | | input | Coordinate-level trusted input via CDP for targets element selectors can't reach - a <canvas> remote desktop (VNC/RDP/Amazon DCV), a game, a WebGL app. Actions: mouse_move, left/right/middle_click, double_click, left_mouse_down/up, left_click_drag, scroll, type (to the focused element), key (combos like ctrl+c). Coords are CSS viewport pixels (= screenshotPixel / dpr, and screenshot now returns dpr). activate:true to foreground the tab so you can observe | | browser_batch | Run a sequence of tools in one call - navigate → click → fill → press_key → screenshot as a single round trip instead of five. The per-call round trip, not the browser, is what makes multi-step tasks slow, so batching whenever you can predict two or more steps ahead is the single biggest speedup available. Runs sequentially and stops at the first error, reporting what completed plus the failing index and message. Cannot be nested; capped at 50 actions. Allowlisted to tools that add no approval surface when batched: navigation + interaction (navigate, go_back, go_forward, tabs_list, tab_new, tab_activate, click, fill, hover, type, press_key, scroll, wait_for), page reads (snapshot, get_page_text, screenshot, eval_js), pure functions (jwt_decode, response_diff) and inert status/buffer reads (bridge_status, debugger_status, identity_list, session_record_status, watch_status, `ne