# 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](docs/design.md) for the architecture, protocol and security model.

## Requirements

- macOS with Google Chrome 116 or later
- [bun](https://bun.sh)
- At least one MCP client: Claude Code, Codex CLI or Grok Build CLI

## Install

```bash
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):

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

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

```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

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

## License

[MIT](LICENSE)