https://github.com/wxtsky/byob
Bring Your Own Browser — let your AI agent use the Chrome you already have open
https://github.com/wxtsky/byob
ai-agent browser-automation bun chrome-debugger chrome-extension claude-code cursor mcp mcp-server native-messaging typescript wxt
Last synced: 9 days ago
JSON representation
Bring Your Own Browser — let your AI agent use the Chrome you already have open
- Host: GitHub
- URL: https://github.com/wxtsky/byob
- Owner: wxtsky
- License: mit
- Created: 2026-04-25T06:19:21.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-25T16:56:32.000Z (4 months ago)
- Last Synced: 2026-04-25T17:33:49.593Z (4 months ago)
- Topics: ai-agent, browser-automation, bun, chrome-debugger, chrome-extension, claude-code, cursor, mcp, mcp-server, native-messaging, typescript, wxt
- Language: TypeScript
- Homepage: https://github.com/wxtsky/byob
- Size: 1.69 MB
- Stars: 56
- Watchers: 1
- Forks: 5
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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)
---
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
```
On Windows, run the same command from Git Bash or MSYS2. The script checks prerequisites (Node.js ≥ 20, bun, Chrome/Edge/Brave), clones the repo, builds everything, and walks you through MCP registration interactively. If bun is not installed, it offers to install it for you using the native installer for your OS.
> Set `BYOB_INSTALL_DIR` to change the install location (default: `~/byob`). Advanced: `BYOB_REPO`, `BYOB_REF`, and `BYOB_SKIP_SETUP=1` are supported for forks, pinned refs, and CI-style dependency install only.
### Manual install
Prefer to do it yourself?
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
```
`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. Claude Code gets the bundled
plugin (Skill + auto-started MCP); other clients get their MCP config.
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 — Claude Code plugin / manual MCP reference
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:
Claude Code plugin (recommended)
```sh
claude plugin marketplace add wxtsky/byob
claude plugin install byob@byob --scope user
```
Run `/reload-plugins` in Claude Code after installing. The plugin includes the
`/byob:control-chrome` Skill and starts its bundled MCP server automatically;
do not also register a second `byob` MCP server.
For local development without installing:
```sh
claude --plugin-dir /path/to/byob/plugins/byob
```
Claude Code manual MCP fallback
```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`.
Codex CLI
```sh
codex mcp add byob -- /path/to/tsx /path/to/byob-mcp.ts
```
Cursor
Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
```json
{
"mcpServers": {
"byob": {
"command": "/path/to/tsx",
"args": ["/path/to/byob-mcp.ts"]
}
}
}
```
Windsurf
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"]
}
}
}
```
Cline (VS Code)
Open Cline sidebar → MCP Servers → Configure, then add (same JSON format):
```json
{
"mcpServers": {
"byob": {
"command": "/path/to/tsx",
"args": ["/path/to/byob-mcp.ts"]
}
}
}
```
> 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 `` 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 `` |
| `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 ``. |
| `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. |
| `browser_snapshot` | Get a compact accessibility tree with reusable element references. |
| `browser_new_tab` | Create an empty or pre-navigated background tab. |
| `browser_reload` | Reload a tab and wait for it to finish loading. |
| `browser_get_js_dialog` | Inspect an alert / confirm / prompt without resolving it. |
| `browser_handle_js_dialog` | Explicitly accept or dismiss a JavaScript dialog. |
| `browser_history` | Search Chrome history with optional terms and date bounds. |
| `browser_clipboard_read_text` | Read plain text from the system clipboard. |
| `browser_clipboard_write_text` | Replace the system clipboard with plain text. |
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.
- **Per-site allow/deny lists.** Set them from the extension's service-worker console:
```js
// never let the agent touch these, with any tool
chrome.storage.local.set({ BYOB_DENIED_DOMAINS: ['**.chase.com', 'mail.proton.me'] })
// or lock the agent to a fixed set of sites for a session
chrome.storage.local.set({ BYOB_ALLOWED_DOMAINS: ['**.github.com'] })
```
Patterns: `example.com` (exact), `*.example.com` (subdomains only), `**.example.com` (apex + subdomains), `*` (everything). Deny wins over allow. A non-empty allow list means allow-list-only. Enforced when byob attaches the debugger, so it covers **every** tool — including the ones that take a bare `tabId` like `browser_click` and `browser_get_cookies`.
- **Credential fields are redacted.** Values in password / OTP / card / email inputs are never sent to the model; they surface as `[redacted]`.
- 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.