byob

Bring Your Own Browser — let your AI assistant use the Chrome you already have open.

English · 中文

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"

Install

Quick install (recommended)

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

git clone https://github.com/wxtsky/byob
cd byob
bun install
bun run setup

bun run setup handles the following automatically:

• Generates a unique extension key for you
• Builds the Chrome extension
• Writes the config that lets Chrome talk to byob
• Opens chrome://extensions automatically (macOS / Windows)
• Prints the MCP server command you'll need in Step 4

Step 2 — Load extension in Chrome

The setup script opens chrome://extensions automatically on macOS / Windows. If it didn't open, navigate there manually.

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 — Register the MCP server with your AI tool

The setup script lets you choose your AI tool(s) interactively and registers automatically:

• CLI tools (Claude Code, Codex): runs the registration command directly
• JSON-config tools (Cursor, Windsurf, Cline): writes the config file for you

Reference for manual configuration:

claude mcp add byob -s user -- /path/to/tsx /path/to/byob-mcp.ts

codex mcp add byob -- /path/to/tsx /path/to/byob-mcp.ts

{
  "mcpServers": {
    "byob": {
      "command": "/path/to/tsx",
      "args": ["/path/to/byob-mcp.ts"]
    }
  }
}

{
  "mcpServers": {
    "byob": {
      "command": "/path/to/tsx",
      "args": ["/path/to/byob-mcp.ts"]
    }
  }
}

{
  "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 — Verify

bun run doctor

If all checks pass (4 green ✓), the installation is complete. Open a new session in your AI tool and try "use byob to read ...".

Tools

9 of these tools support framePath to reach into nested iframes (including cross-origin).

Full schemas: 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

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

Run bun run doctor for detailed diagnostics on which step failed.

Platform notes

More

• Changelog
• Contributing
• Design notes
• Test checklist

MIT licensed. byob has broad access to your browser — only use it on machines and accounts you own.