Content
<div align="center">
<img src="assets/logo.svg" alt="byob" width="120"/>
# byob
**Bring Your Own Browser** — let your AI assistant use the Chrome you already have open.
[](LICENSE) [](https://modelcontextprotocol.io) [](https://developer.chrome.com/docs/extensions/mv3/intro/) [](CHANGELOG.md)
**English** · [中文](README.zh-CN.md)
</div>
---
byob is a local MCP server that lets AI coding tools (Claude Code, Cursor, Cline, Windsurf, etc.) directly control **your real Chrome** — the one where you're already logged into everything.
```
"read my Twitter timeline and summarize the top 5 posts"
"google 'mcp protocol spec', click the first result, read the page"
"take a screenshot of example.com"
"grab my GitHub session cookie so I can curl with it"
"open my Gmail tab and tell me how many unread"
```
| | WebFetch | Headless Puppeteer | **byob** |
|---|:-:|:-:|:-:|
| Sees logged-in pages | ❌ | ⚠️ manual cookie copy | ✅ already logged in |
| Passes bot detection | ❌ | ❌ | ✅ real human browser |
| Setup time | 0 | hours | **~5 min** |
| Cloud cost | free | $$ | free |
---
## Install
### Quick install (recommended)
```sh
curl -fsSL https://raw.githubusercontent.com/wxtsky/byob/main/install.sh | bash
```
The script checks prerequisites (Node.js ≥ 20, bun, Chrome), clones the repo, builds everything, and walks you through MCP registration interactively. If bun is not installed, it offers to install it for you.
> Set `BYOB_INSTALL_DIR` to change the install location (default: `~/byob`).
### Manual install
<details>
<summary>Prefer to do it yourself?</summary>
Requires **Node.js ≥ 20**, **bun**, **Chrome**, and any MCP-compatible AI tool.
```sh
git clone https://github.com/wxtsky/byob
cd byob
bun install
bun run setup
```
</details>
`bun run setup` walks through the install interactively:
1. Pick output language (English / 中文)
2. Generates a unique extension key for you
3. Builds the Chrome extension
4. Writes the config that lets Chrome talk to byob
5. Prompts you to multi-select your AI tools, then registers each one (CLI tools via their `mcp add` command, JSON-config tools by writing the config file directly)
After the script finishes, three manual steps remain:
### Step 2 — Load extension in Chrome
Open `chrome://extensions` in Chrome.
1. Top-right → turn ON **Developer mode**
2. Top-left → click **Load unpacked**
3. Select the folder printed in your terminal, something like:
```
/your/path/to/byob/packages/extension/output/chrome-mv3
```
### Step 3 — Restart Chrome
**Quit Chrome completely** (`⌘Q` on Mac / close all windows on Windows), then reopen.
> Closing a single tab or window is not sufficient — Chrome only reads the Native Messaging config at startup.
### Step 4 — (Reference) Manual MCP registration
The setup script registers your selected tools automatically. The block below is for reference only — use it if you skipped the prompt or want to register a different tool later:
<details open>
<summary><b>Claude Code</b></summary>
```sh
claude mcp add byob -s user -- /path/to/tsx /path/to/byob-mcp.ts
```
To enable `browser_eval`, add `-e BYOB_ALLOW_EVAL=1` after `-s user`.
</details>
<details>
<summary><b>Codex CLI</b></summary>
```sh
codex mcp add byob -- /path/to/tsx /path/to/byob-mcp.ts
```
</details>
<details>
<summary><b>Cursor</b></summary>
Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
```json
{
"mcpServers": {
"byob": {
"command": "/path/to/tsx",
"args": ["/path/to/byob-mcp.ts"]
}
}
}
```
</details>
<details>
<summary><b>Windsurf</b></summary>
Add to `~/.codeium/windsurf/mcp_config.json` (same JSON format as Cursor):
```json
{
"mcpServers": {
"byob": {
"command": "/path/to/tsx",
"args": ["/path/to/byob-mcp.ts"]
}
}
}
```
</details>
<details>
<summary><b>Cline (VS Code)</b></summary>
Open Cline sidebar → MCP Servers → Configure, then add (same JSON format):
```json
{
"mcpServers": {
"byob": {
"command": "/path/to/tsx",
"args": ["/path/to/byob-mcp.ts"]
}
}
}
```
</details>
> The actual paths are printed by the setup script. The examples above use shortened paths for readability.
> To enable `browser_eval`, add `"env": { "BYOB_ALLOW_EVAL": "1" }` to the config (or `-e BYOB_ALLOW_EVAL=1` for CLI tools).
### Step 5 — Wait for setup to confirm the bridge is online
After you finish steps 2 and 3 (load the extension and ⌘Q-restart Chrome), **setup auto-detects the bridge coming online** and prints `✓ bridge online`. The installation is complete — open a new session in your AI tool and try _"use byob to read ..."_.
If you exited setup early with Ctrl+C, or want to check the state later:
```sh
bun run doctor
```
`bun run doctor` prints actionable fixes under every `✗` (e.g. "⌘Q-restart Chrome", "extension ID mismatch", etc.).
---
## Tools
| Tool | What it does |
|---|---|
| `browser_read` | Open a page, scroll through, read all text |
| `browser_read_markdown` | Same, returns clean markdown (no nav/ads) |
| `browser_extract_table` | Pull `<table>` elements as JSON |
| `browser_get_console_logs` | Snapshot console.log / warn / error |
| `browser_start_record_network` | Start recording HTTP + WebSocket traffic |
| `browser_stop_record_network` | Stop recording, export JSON or HAR |
| `browser_screenshot` | Screenshot → saved to disk |
| `browser_download_images` | Download all images from a page |
| `browser_click` | Click a button or link |
| `browser_type` | Type into an input (optionally press Enter) |
| `browser_press_key` | Send a keyboard key (Enter, Escape, F5, ArrowDown, ...) |
| `browser_hover` | Hover the mouse over an element to trigger tooltips/menus |
| `browser_select` | Choose an option in a native `<select>` |
| `browser_scroll` | Scroll to top/bottom, an element, or a Y coordinate |
| `browser_get_html` | Get raw HTML of an element or the whole page |
| `browser_get_cookies` | Export cookies for `curl` / scripts |
| `browser_navigate` | Open a URL in a new or existing tab |
| `browser_go_back` | Go back one step in browser history |
| `browser_go_forward` | Go forward one step in browser history |
| `browser_wait_for` | Wait for an element to appear |
| `browser_list_tabs` | List all open tabs |
| `browser_switch_tab` | Switch to a tab |
| `browser_close_tab` | Close a tab by tabId |
| `browser_eval` | Run JavaScript on the page (off by default) |
| `browser_set_cookies` | Write a cookie via `chrome.cookies.set` (CHIPS-aware). |
| `browser_print_pdf` | Save current page as PDF (default `~/.byob/pdfs/`). |
| `browser_get_storage` | Read `localStorage` / `sessionStorage` for an origin. |
| `browser_get_performance` | Page Web Vitals + navigation timing. |
| `browser_upload_file` | Upload local files to `<input type="file">`. |
| `browser_intercept_start` | Start a stateful request-interception session. |
| `browser_intercept_stop` | Stop a `browser_intercept_start` session and return hit stats. |
| `browser_drag` | Drag the mouse from one point to another (linear interpolation). |
| `browser_emulate_device` | Emulate mobile/tablet viewport / DPR / touch / UA. |
17 of these tools support `framePath` to reach into nested iframes (including cross-origin).
Full schemas: [`shared/src/schemas.ts`](shared/src/schemas.ts)
---
## How it works
```
AI tool → byob-mcp → byob-bridge → Chrome extension → your tab
(stdio) (Unix socket) (Native Messaging) (Chrome DevTools Protocol)
```
All communication stays local. No data leaves your machine. When Chrome closes, all byob processes exit automatically.
---
## Everyday commands
```sh
bun run setup # install or re-install
bun run doctor # check what's working
bun run bridges # list running bridge processes
bun run logs # tail the bridge log
bun run unsetup # remove everything
```
All run from the byob repo root.
---
## Reliability
- **End-to-end cancellation.** `Ctrl+C` propagates through the entire chain (MCP → bridge → extension → Chrome), cleanly detaching all debug sessions.
- **DevTools conflict handling.** If DevTools is open on a tab, `browser_eval` automatically falls back to `chrome.scripting.executeScript`.
- **Sleep/wake recovery.** After a laptop sleep cycle, byob resets all debug sessions so the next call starts from a clean state.
---
## Security
- `browser_eval` is **off by default** — enable with `BYOB_ALLOW_EVAL=1`. Every call logs + notifies.
- `chrome://`, `file://`, Google/MS/Apple login pages are blocked by default.
- Each install gets a unique extension key — no collisions.
- Socket files are `0600`, dirs are `0700`. Other users can't see them.
- **Zero outbound network traffic.** No analytics, no pings, no crash reports.
- Chrome displays a "byob is debugging this browser" banner on active tabs. This is a Chrome security feature and cannot be suppressed.
---
## Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| `No live bridge` | Chrome not running or extension disabled | Check `chrome://extensions` |
| `cdp_attach_failed` | DevTools open on that tab | Close DevTools |
| `url_forbidden` | URL on the blocklist | See Security section |
| `extension_not_connected` | Extension lost connection | Reload at `chrome://extensions` |
| Nothing works after install | Chrome was not fully restarted | Quit Chrome completely (`⌘Q`) and reopen |
Run `bun run doctor` for detailed diagnostics on which step failed.
---
## Platform notes
| Platform | Auto | Manual |
|---|---|---|
| **macOS** | Auto-registers selected MCP tools | Open `chrome://extensions` and load the unpacked extension |
| **Windows** | Same + writes Native Messaging host to registry | Same as macOS |
| **Linux** | Auto-registers selected MCP tools | Same as macOS |
---
## More
- [Changelog](CHANGELOG.md)
- [Contributing](CONTRIBUTING.md)
- [Design notes](docs/superpowers/specs/2026-04-25-byob-design.md)
- [Test checklist](docs/e2e-checklist.md)
MIT licensed. byob has broad access to your browser — only use it on machines and accounts you own.
