Quick Start • Features • Architecture • Install • 中文
Browser as a Tool for Any Agent: Let any AI agent, LLM, or script control your local browser. Use the included CLI, the Claude Code skill, or any integration that speaks the bridge protocol. Your sessions, cookies, and credentials stay local.
Browsing news with an agent
Managing Gmail with an agent
One-line pitch: Browser Bridge turns your local Chrome into a reusable tool for any agent. One browser, any LLM, script, or terminal command — while keeping your data local.
- 🤖 Agent-ready interface — one bridge protocol, consumed via CLI, Claude Code skill, or custom integration.
- 🔒 Local session, cloud control — reuse your logged-in browser; no cloud browser or cookie sync needed.
- 🌉 WebSocket bridge — agents talk to a server, server talks to a local proxy, proxy talks to Chrome.
- 🧩 Chrome Extension (MV3) — built with Vite, loads as an unpacked extension.
- ⚡ Bun + TypeScript — fast startup, strict types, one package manager for the whole monorepo.
- 🧪 Dev-friendly — hot reload for server, proxy, and extension.
- 🤖 MCP server — Streamable HTTP MCP server exposes browser tools to Claude Desktop, Cursor, and other MCP clients.
curl -fsSL https://github.com/dkisser/browser-bridge/releases/latest/download/install.sh | bashLoad ~/Browser-Bridge/extension/ as an unpacked extension in Chrome. The bridge services start automatically.
bridge navigate https://github.com --browser <browser-id>That’s it. The command travels from CLI → WebSocket server → local proxy → Chrome extension → browser.
Use
bridge browser:listto see the<browser-id>of your connected Chrome instance.
The bridge CLI is just one consumer of the bridge protocol. Browser Bridge ships with a ready-to-use Claude Code skill in ./skills, and anything that can open a WebSocket — for example, an MCP server you build, a custom SDK, or another agent framework — can send commands the same way.
Browser Bridge also exposes a Streamable HTTP MCP server alongside the WebSocket server. Once bridge up (or bun run dev:websocket) is running, add http://localhost:3003/mcp to your MCP client — Claude Desktop, Cursor, or any client that supports Streamable HTTP.
The MCP server exposes browser-control tools such as navigate, click, type, screenshot, get_text, and more. Each tool can target any connected browser, so you can drive Chrome directly from an MCP-enabled agent without using the CLI.
See docs/mcp-setup.md for client configuration, environment variables, and the full tools list.
┌─────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ CLI / Agent │ ───▶ │ WebSocket │ ───▶ │ Local Proxy │ ───▶ │ Chrome │
│ │ │ Server │ │ (your machine) │ │ Extension │
└─────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────┐
│ Chrome │
│ (browser) │
└─────────────┘
| Layer | Component | Role |
|---|---|---|
| Cloud / shared | Interfaces | Agent-facing entry points: CLI, Claude Code skill, or any custom integration. |
| Cloud / shared | WebSocket Server | Routes commands to the right local proxy. |
| Local | Local Proxy | Maintains the outbound connection from your machine. |
| Local | Chrome Extension | Receives messages and executes browser actions. |
See docs/architecture-diagram.html for the full diagram.
curl -fsSL https://github.com/dkisser/browser-bridge/releases/latest/download/install.sh | bashThe installer downloads the runtime, exposes ~/Browser-Bridge/extension/ as a symlink for Chrome, and starts the bridge services. You only need to load the unpacked extension in Chrome.
On macOS, the installer also enables login auto-start, so bridge services start automatically after you log in. To disable this, pass --no-autostart or run bridge autostart off later.
To reinstall the same version, pass --force. To install a specific version, set BB_VERSION=vX.Y.Z.
If you already have Claude Code, clone the repo and run the installer from the project root with --with-skills to install Browser Bridge plus the ready-to-use skill in ./skills:
git clone https://github.com/dkisser/browser-bridge.git
cd browser-bridge
./install/install.sh --with-skillsUse --skills-dir <path> if you want to install skills somewhere other than ~/.claude/skills/. Use --no-skills to explicitly skip skill installation.
By default, the curl installer does not install skills; use --with-skills when you want them.
See the Development section below. You only need this if you are contributing to Browser Bridge.
The steps below are for contributors/developers only. End users do not need to install
bunorgit.
# 1. Install dependencies
bun install
# 2. Start the WebSocket server
bun run dev:websocket
# 3. In another terminal, start the local proxy
bun run dev:local-proxy
# 4. In a third terminal, build the extension
bun run dev:extension
# 5. Load apps/extension/dist/ as an unpacked extension in Chrome
# 6. Run the CLI
bun run cliBrowser-Bridge/
├── apps/
│ ├── cli/ # CLI entrypoint (one bridge protocol consumer)
│ ├── extension/ # Chrome Extension (Manifest V3, Vite)
│ ├── local-proxy/ # Local WebSocket proxy
│ └── websocket/ # WebSocket server, client, and protocol
├── packages/
│ └── shared/ # Shared constants and utilities
├── install/ # One-line installer scripts
└── docs/ # Architecture diagrams and guides
- Runtime & package manager: Bun
- Extension build: Vite + Manifest V3
- Transport: WebSocket
- Type checking: TypeScript (strict)
- Linting & formatting: Biome
- Testing: Bun test runner + Bats for install scripts
- Only authenticated extensions can register with the WebSocket server.
- Commands are routed through the server; the local network is not exposed directly.
- The local proxy connects outbound to the server and extension, minimizing open ports.
Contributions are welcome. Please open an issue first to discuss significant changes.