Browser Bridge

Reliable local Chrome control for coding agents.

Browser Bridge drives your real, local Chrome (not headless) and inspects page state through a Chrome extension plus a local daemon. You stay in the loop with your existing tabs and login state.

🏁 Install + Quickstart (Do This First)

You need Node.js 20+ and Chrome (stable). Browser Bridge is local-only (binds to 127.0.0.1).

1. Install the CLI:

npm i -g @btraut/browser-bridge
browser-bridge --help

2. Run the installer:

browser-bridge install

Select your client(s) (Codex, Claude, Cursor, etc).

3. Install the Chrome extension:

• Chrome Web Store listing is pending. For now, install manually.
• Download the latest pre-built extension zip from GitHub Releases (Assets), unzip it.
• Chrome -> chrome://extensions -> enable Developer mode -> Load unpacked -> select the folder with manifest.json.

Build the extension from source (instead of using a release zip)

npm install
npm run build

Then load the unpacked extension from packages/extension/.

4. Try it:

Use Browser Bridge to navigate to https://example.com.

If Chrome shows a Browser Bridge permissions prompt, approve it, then tell the agent to retry.

CLI sanity check (debugging)

browser-bridge session create
# Use the session_id from the output for the next commands.
browser-bridge drive navigate --session-id <id> --url https://example.com
browser-bridge inspect dom-snapshot --session-id <id> --max-nodes 2000
browser-bridge session close --session-id <id>

Notes:

• inspect dom-snapshot defaults to --format ax; --max-nodes is only supported for AX snapshots.

✨ What You Get

What makes it different:

• Real browser state: operate on your actual Chrome profile (tabs, cookies, logins, extensions).
• Two-plane architecture: a drive plane that does what a user does (click, type, navigate), plus an inspect plane that reads state (DOM, console, screenshots). This separation makes runs less flaky and lets inspection happen in parallel.
• Safe-by-default drive permissions: drive.* actions are blocked on new sites until you approve them. You can allow once, always allow (per-site allowlist you can audit/revoke), or enable a clearly-labeled bypass mode if you want zero guardrails.
• Token-efficient inspection: stable element refs like @e1 (find once, reuse everywhere) plus knobs to bound output (--max-nodes, --compact, --interactive, --selector).
• Structured errors for agents: stable error codes with a retryable flag (no more guessing whether to retry).
• Recovery-first: sessions have an explicit state machine with session.recover() and diagnostics doctor.
• Inspect beyond screenshots: DOM snapshots (AX + HTML) and inspect dom-diff to detect page changes.

🔒 Site Permissions (Drive Actions)

Browser Bridge is intentionally safe: drive actions (drive.navigate, click, type, etc.) require per-site approval. inspect.* is not gated, so agents can inspect first and only ask for permission when it's time to click/type.

How approvals work (click to expand)

• The first time a drive.* action targets a new site, Chrome opens a small permissions prompt.
• Click Allow this action to allow once (no allowlist entry).
• Click Always allow actions on this site to add the site to your approved-sites allowlist.
• Click Decline to fail the command with PERMISSION_DENIED (non-retryable).
• If you ignore the prompt, the command fails with PERMISSION_PROMPT_TIMEOUT (retryable). Default wait is 30 seconds; approve the prompt, then retry the command.

Manage approvals (and bypass mode):

• Open the extension options page from chrome://extensions (Browser Bridge -> Extension options) or from the Extensions toolbar menu (Browser Bridge -> Extension options).
• The options page shows your Approved sites allowlist with revoke controls.
• Switch Permission mode to Bypass (dangerous) to skip the allowlist and prompts entirely.
• In bypass mode, the agent can take actions on any website without asking.
• Restricted URLs (for example chrome:// and file://) are still blocked.

🧰 Tools (MCP + CLI)

The CLI mirrors the MCP tool surface.

All MCP tools (click to expand)

session

• session.create
• session.status
• session.recover
• session.close

drive

• drive.navigate
• drive.go_back
• drive.go_forward
• drive.back
• drive.forward
• drive.click
• drive.hover
• drive.select
• drive.type
• drive.fill_form
• drive.drag
• drive.handle_dialog
• drive.key
• drive.key_press
• drive.scroll
• drive.wait_for
• drive.tab_list
• drive.tab_activate
• drive.tab_close

dialog

• dialog.accept
• dialog.dismiss

inspect

• inspect.dom_snapshot
• inspect.dom_diff
• inspect.find
• inspect.extract_content
• inspect.page_state
• inspect.console_list
• inspect.network_har
• inspect.evaluate
• inspect.performance_metrics

artifacts

• artifacts.screenshot

misc

• health_check
• diagnostics.doctor

🧩 Skills (Agent Clients)

Browser Bridge skills work across many agent clients, including Codex and Claude Code.

Easiest option (recommended):

browser-bridge install

Or copy the Browser Bridge skill into your agent skills directory (advanced):

# From this repo:
# cp -R docs/skills/browser-bridge ~/.agents/skills/browser-bridge
# cp -R docs/skills/browser-bridge ~/.claude/skills/browser-bridge

# From npm (global install):
cp -R "$(npm root -g)/@btraut/browser-bridge/skills/browser-bridge" ~/.agents/skills/browser-bridge
cp -R "$(npm root -g)/@btraut/browser-bridge/skills/browser-bridge" ~/.claude/skills/browser-bridge

Restart your agent app if it does not pick up the new skill automatically.

🧪 MCP Server (Optional)

The MCP server runs over stdio and forwards tool calls to Core. It is optional, since you can use the CLI directly. MCP clients launch it automatically when needed, so you typically do not run it yourself.

• Easiest option: browser-bridge mcp install
• Manual start (debugging): browser-bridge mcp
• Use your MCP client to call tools/list, then session.create
• Override Core host/port with --host, --port, or BROWSER_BRIDGE_CORE_HOST / BROWSER_BRIDGE_CORE_PORT.

Manual MCP setup (advanced)

Codex:

codex mcp add browser-bridge -- browser-bridge mcp

Optional custom host/port:

codex mcp add browser-bridge \
  --env BROWSER_BRIDGE_CORE_HOST=127.0.0.1 \
  --env BROWSER_BRIDGE_CORE_PORT=3210 \
  -- browser-bridge mcp

Claude Code:

claude mcp add --transport stdio browser-bridge -- browser-bridge mcp

Optional custom host/port:

claude mcp add --transport stdio browser-bridge \
  --env BROWSER_BRIDGE_CORE_HOST=127.0.0.1 \
  --env BROWSER_BRIDGE_CORE_PORT=3210 \
  -- browser-bridge mcp

🩺 Diagnostics

• CLI: browser-bridge diagnostics doctor --session-id <id>
• Reports extension and debugger status alongside session state.

🔧 Recovery

If drive or inspect gets into a bad state, recovery is explicit:

• browser-bridge session recover --session-id <id>
• Then retry the failed operation once (tools report whether failures are retryable).

🧹 Session TTL (Core Daemon)

The Core daemon keeps sessions in memory. By default, it automatically cleans up idle sessions after 1 hour.

• BROWSER_BRIDGE_SESSION_TTL_MS: Idle session TTL in milliseconds. Set to 0 to disable cleanup.
• BROWSER_BRIDGE_SESSION_CLEANUP_INTERVAL_MS: Cleanup interval in milliseconds. Defaults to a small value relative to the TTL.