browser-bridge

Local-only browser control for AI agents. Any MCP client (Claude Code, Codex CLI, Grok Build CLI) can drive one labelled Chrome profile per conversation. Nothing leaves the machine: no cloud relay, no network port, no telemetry.

It is built for people who keep several signed-in Chrome profiles (for example work and personal) and run several agent conversations at once:

• Each conversation binds to one profile, and only after you confirm it.

• Each conversation works only in its own tab group, so conversations never act in each other's tabs.

• A closed profile pauses the conversation instead of sending its actions to another profile.

See docs/design.md for the architecture, protocol and security model.

Requirements

• macOS with Google Chrome 116 or later

• bun

• At least one MCP client: Claude Code, Codex CLI or Grok Build CLI

Related MCP server: Umbra MCP Server

Install

git clone https://github.com/jbjzq/browser-bridge.git
cd browser-bridge
bun install
bun run setup

setup compiles bb-hub, bb-mcp and bb-native-host into ~/.browser-bridge/bin/, installs the Chrome native messaging manifest, registers bb-mcp with every installed agent CLI, copies the built extension to ~/Desktop/browser-bridge-extension (override with BB_EXT_DIR), and prints how to load it.

Then, in each Chrome profile you want agents to use:

1. Open chrome://extensions and turn on Developer mode.

2. Click Load unpacked and choose the extension folder printed by setup.

3. Click the browser-bridge icon and set a label, such as work or personal.

A label belongs to the first profile that claims it, even while that profile is closed. Ownership is kept in ~/.browser-bridge/labels.json.

Use

In a conversation the agent calls bb_list_browsers, proposes a browser with bb_select_browser, asks you to confirm, then calls bb_confirm_browser. From then on it works only in its own tab group in that profile. To hand it one of your tabs, give it the URL; it calls bb_adopt_tab.

Per-repo browser hint

Add --prefer <label> in the repo's own MCP config so the agent proposes the right browser first. It is a hint only; you still confirm. Replace /Users/<you> with your home directory.

Claude Code (.mcp.json in the repo, overrides the user-scope entry):

{ "mcpServers": { "browser-bridge": { "command": "/Users/<you>/.browser-bridge/bin/bb-mcp", "args": ["--prefer", "work"] } } }

Codex (.codex/config.toml) and Grok Build (.grok/config.toml):

[mcp_servers.browser-bridge]
command = "/Users/<you>/.browser-bridge/bin/bb-mcp"
args = ["--prefer", "personal"]

Security

• The hub listens on a Unix socket (0600, in a 0700 directory), so only your macOS user can connect. There is no TCP port.

• Chrome starts the native host only for this extension's id.

• Password, payment-card and one-time-code fields are redacted in page snapshots, and the agent cannot type into them.

• bb_upload only sends non-hidden files from ~/Downloads, ~/Desktop and the conversation's folder.

• A web page can still contain text that tries to steer the agent (prompt injection). Tab confinement limits the damage to the conversation's own tabs in the bound profile; it does not prevent it there. bb_eval runs arbitrary JavaScript in those tabs.

Troubleshooting

• Popup says "Not connected": run bun run setup again and reload the extension. The native host manifest must list this extension's id.

• label_duplicate in the popup: another profile already uses that label.

• browser_not_running: the bound profile is closed. Open it; the binding is kept.

• bb_upload refuses a file: the file is outside the allowed folders or hidden. Add folders with BB_UPLOAD_DIRS=/path/a:/path/b in the MCP server's environment.

• The yellow "started debugging this browser" banner is Chrome's and cannot be hidden by the extension.

Develop

bun test            # unit + integration
bun run typecheck
bun run build:extension

License

MIT