Skip to content
Back to search

byob

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/wxtsky/byob with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/wxtsky/byob'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wxtsky--byob/badge.svg)](/listings/wxtsky--byob)

HTML

<a href="/listings/wxtsky--byob"><img src="/api/listings/wxtsky--byob/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Quick install (recommended)

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

<details> <summary>Prefer to do it yourself?</summary>

Requires **Node.js ≥ 20**, **bun**, **Chrome**, and any MCP-compatible AI tool.

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. 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:

<details open> <summary><b>Claude Code plugin (recommended)</b></summary>

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:

claude --plugin-dir /path/to/byob/plugins/byob

</details>

<details> <summary><b>Claude Code manual MCP fallback</b></summary>

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

To enable `browser_evaluate`, add `-e BYOB_ALLOW_EVAL=1` after `-s user`.

</details>

<details> <summary><b>Codex CLI</b></summary>

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

{
  "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):

{
  "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):

{
  "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_evaluate`, add `"env": { "BYOB_ALLOW_EVAL": "1" }` to the config (or `-e BYOB_ALLOW_EVAL=1` for CLI tools).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 23 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "byob",
  3. "owner": {
  4. "name": "wxt",
  5. "url": "https://github.com/wxtsky"
  6. },
  7. "description": "Claude Code plugins from the byob project.",
  8. "plugins": [
  9. {
  10. "name": "byob",
  11. "displayName": "byob Chrome Control",
  12. "source": "./plugins/byob",
  13. "description": "Control the user's real Chrome with the byob extension, native bridge, MCP tools, and browser-control skill.",
  14. "category": "development",
  15. "tags": [
  16. "chrome",
  17. "browser",
  18. "automation",
  19. "mcp"
  20. ]
  21. }
  22. ]
  23. }
README.md · README · 339 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="assets/logo.svg" alt="byob" width="120"/>
  3. # byob
  4. **Bring Your Own Browser** — let your AI assistant use the Chrome you already have open.
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-22c55e.svg)](LICENSE) [![MCP](https://img.shields.io/badge/MCP-stdio-0a0a0a.svg)](https://modelcontextprotocol.io) [![Chrome MV3](https://img.shields.io/badge/Chrome-MV3-f59e0b.svg)](https://developer.chrome.com/docs/extensions/mv3/intro/) [![v0.5](https://img.shields.io/badge/v0.5-ready-22c55e.svg)](CHANGELOG.md)
  6. **English** · [中文](README.zh-CN.md)
  7. </div>
  8. ---
  9. 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.
  10. ```
  11. "read my Twitter timeline and summarize the top 5 posts"
  12. "google 'mcp protocol spec', click the first result, read the page"
  13. "take a screenshot of example.com"
  14. "grab my GitHub session cookie so I can curl with it"
  15. "open my Gmail tab and tell me how many unread"
  16. "fill in this form with my details and submit it"
  17. ```
  18. | | WebFetch | Headless Puppeteer | **byob** |
  19. |---|:-:|:-:|:-:|
  20. | Sees logged-in pages | ❌ | ⚠️ manual cookie copy | ✅ already logged in |
  21. | Passes bot detection | ❌ | ❌ | ✅ real human browser |
  22. | Setup time | 0 | hours | **~5 min** |
  23. | Cloud cost | free | $$ | free |
  24. Compared with tools that attach over Chrome's remote-debugging port (DevTools MCP, agent-browser, Playwright `--cdp`): byob is an extension, so there's **no debugging port to open, no "Allow remote debugging?" prompt on every connection**, and nothing else on your machine can hijack your logged-in browser through it.
  25. ---
  26. ## Install
  27. ### Quick install (recommended)
  28. ```sh
  29. curl -fsSL https://raw.githubusercontent.com/wxtsky/byob/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 44 on GitHub
  30. ```
  31. 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.
  32. > 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.
  33. ### Manual install
  34. <details>
  35. <summary>Prefer to do it yourself?</summary>
  36. Requires **Node.js ≥ 20**, **bun**, **Chrome**, and any MCP-compatible AI tool.
  37. ```sh
  38. git clone https://github.com/wxtsky/byob
  39. cd byob
  40. bun install
  41. bun run setup
  42. ```
  43. </details>
  44. `bun run setup` walks through the install interactively:
  45. 1. Pick output language (English / 中文)
  46. 2. Generates a unique extension key for you
  47. 3. Builds the Chrome extension
  48. 4. Writes the config that lets Chrome talk to byob
  49. 5. Prompts you to multi-select your AI tools. Claude Code gets the bundled
  50. plugin (Skill + auto-started MCP); other clients get their MCP config.
  51. After the script finishes, three manual steps remain:
  52. ### Step 2 — Load extension in Chrome
  53. Open `chrome://extensions` in Chrome.
  54. 1. Top-right → turn ON **Developer mode**
  55. 2. Top-left → click **Load unpacked**
  56. 3. Select the folder printed in your terminal, something like:
  57. ```
  58. /your/path/to/byob/packages/extension/output/chrome-mv3
  59. ```
  60. ### Step 3 — Restart Chrome
  61. **Quit Chrome completely** (`⌘Q` on Mac / close all windows on Windows), then reopen.
  62. > Closing a single tab or window is not sufficient — Chrome only reads the Native Messaging config at startup.
  63. ### Step 4 — Claude Code plugin / manual MCP reference
  64. 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:
  65. <details open>
  66. <summary><b>Claude Code plugin (recommended)</b></summary>
  67. ```sh
  68. claude plugin marketplace add wxtsky/byob
  69. claude plugin install byob@byob --scope user
  70. ```
  71. Run `/reload-plugins` in Claude Code after installing. The plugin includes the
  72. `/byob:control-chrome` Skill and starts its bundled MCP server automatically;
  73. do not also register a second `byob` MCP server.
  74. For local development without installing:
  75. ```sh
  76. claude --plugin-dir /path/to/byob/plugins/byob
  77. ```
  78. </details>
  79. <details>
  80. <summary><b>Claude Code manual MCP fallback</b></summary>
  81. ```sh
  82. claude mcp add byob -s user -- /path/to/tsx /path/to/byob-mcp.ts
  83. ```
  84. To enable `browser_evaluate`, add `-e BYOB_ALLOW_EVAL=1` after `-s user`.
  85. </details>
  86. <details>
  87. <summary><b>Codex CLI</b></summary>
  88. ```sh
  89. codex mcp add byob -- /path/to/tsx /path/to/byob-mcp.ts
  90. ```
  91. </details>
  92. <details>
  93. <summary><b>Cursor</b></summary>
  94. Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
  95. ```json
  96. {
  97. "mcpServers": {
  98. "byob": {
  99. "command": "/path/to/tsx",
  100. "args": ["/path/to/byob-mcp.ts"]
  101. }
  102. }
  103. }
  104. ```
  105. </details>
  106. <details>
  107. <summary><b>Windsurf</b></summary>
  108. Add to `~/.codeium/windsurf/mcp_config.json` (same JSON format as Cursor):
  109. ```json
  110. {
  111. "mcpServers": {
  112. "byob": {
  113. "command": "/path/to/tsx",
  114. "args": ["/path/to/byob-mcp.ts"]
  115. }
  116. }
  117. }
  118. ```
  119. </details>
  120. <details>
  121. <summary><b>Cline (VS Code)</b></summary>
  122. Open Cline sidebar → MCP Servers → Configure, then add (same JSON format):
  123. ```json
  124. {
  125. "mcpServers": {
  126. "byob": {
  127. "command": "/path/to/tsx",
  128. "args": ["/path/to/byob-mcp.ts"]
  129. }
  130. }
  131. }
  132. ```
  133. </details>
  134. > The actual paths are printed by the setup script. The examples above use shortened paths for readability.
  135. > To enable `browser_evaluate`, add `"env": { "BYOB_ALLOW_EVAL": "1" }` to the config (or `-e BYOB_ALLOW_EVAL=1` for CLI tools).
  136. ### Step 5 — Wait for setup to confirm the bridge is online
  137. 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 ..."_.
  138. If you exited setup early with Ctrl+C, or want to check the state later:
  139. ```sh
  140. bun run doctor
  141. ```
  142. `bun run doctor` prints actionable fixes under every `✗` (e.g. "⌘Q-restart Chrome", "extension ID mismatch", etc.).
  143. ---
  144. ## Tools
  145. v0.5 has 25 tools. Elements are targeted by **refs** from the snapshot (`[ref=e12]`), a CSS selector, or x/y.
  146. | Tool | What it does |
  147. |---|---|
  148. | `browser_snapshot` | The page as an accessibility outline with refs — interactive-only, diff, scoped; iframes (even cross-origin) inline |
  149. | `browser_find` | Find by role+name / text / label / placeholder / testId, optionally click/fill/check right away |
  150. | `browser_click` | Click (real mouse events), double/right click, modifiers; auto-waits and reports navigation / new tabs / dialogs |
  151. | `browser_type` | Fill inputs, textareas, contenteditable (React/Vue-safe); per-key mode; submit |
  152. | `browser_press_key` | Keys and combos with real key codes (`Enter`, `Shift+Tab`, `ControlOrMeta+A`) |
  153. | `browser_hover` / `browser_select` / `browser_scroll` / `browser_drag` | Menus, `<select>`, page or container scrolling, HTML5 drag-and-drop |
  154. | `browser_upload_file` | Attach local files to `<input type=file>` |
  155. | `browser_batch` | Many steps in one call (fill a whole form and submit) |
  156. | `browser_wait` | Wait for element state, text, URL, load / network idle |
  157. | `browser_read` | Content as text / markdown (reader mode) / html / links / tables, with outline and filter |
  158. | `browser_screenshot` | Viewport / full page / element / clip → image returned to the model; ref labels; PDF |
  159. | `browser_navigate` | Open a URL in a background tab, back / forward / reload |
  160. | `browser_tabs` | List / open / select / close tabs, search history |
  161. | `browser_console` | Console messages and page errors, buffered |
  162. | `browser_network` | Record traffic (summary / JSON / HAR) or intercept: block / mock / modify |
  163. | `browser_inspect` | Element box / state / styles, Web Vitals |
  164. | `browser_storage` | Cookies and local/session storage — get / set / clear |
  165. | `browser_dialog` | Answer alert / confirm / prompt explicitly |
  166. | `browser_emulate` | Device, dark mode, geolocation, timezone, locale, offline, headers |
  167. | `browser_clipboard` | Read / write clipboard text |
  168. | `browser_download_images` | Save a page's images |
  169. | `browser_evaluate` | Run page JavaScript (only with `BYOB_ALLOW_EVAL=1`) |
  170. Schemas: [`shared/src/tools.ts`](shared/src/tools.ts). Upgrading from 0.4? Tool names changed — see the [changelog](CHANGELOG.md#050).
  171. ---
  172. ## How it works
  173. ```
  174. AI tool → byob-mcp → byob-bridge → Chrome extension → your tab
  175. (stdio) (Unix socket) (Native Messaging) (Chrome DevTools Protocol)
  176. ```
  177. - byob's own page scripts run in an **isolated world**: they share the DOM but not JavaScript with the page — no `window.__byob*`, no `data-byob-*` attributes, nothing a site can see or tamper with.
  178. - Refs live in the extension's memory, bound to Chrome's backend node ids; they survive re-renders and are refused (never silently re-targeted) after navigation.
  179. - Each MCP client session has its own working tab; tabs the agent opens are grouped under **byob** and never steal focus.
  180. All communication stays local. No data leaves your machine. When Chrome closes, all byob processes exit automatically.
  181. ---
  182. ## Everyday commands
  183. ```sh
  184. bun run setup # install or re-install
  185. bun run doctor # check what's working
  186. bun run bridges # list running bridge processes
  187. bun run logs # tail the bridge log
  188. bun run unsetup # remove everything
  189. bun run policy # show / change which sites byob may touch (flags below)
  190. ```
  191. All run from the byob repo root.
  192. ---
  193. ## Reliability
  194. - **Auto-waiting actions.** Before clicking or typing, byob waits until the element is attached, visible, stable, enabled and actually on top at its center; errors say what's wrong ("covered by `<div#cookie-banner>`").
  195. - **Actions report their effects** — navigation (waited for), same-page URL changes, new tabs, JS dialogs — so the agent doesn't have to poll.
  196. - **Dialogs never hang a call.** A click that opens `confirm()` returns immediately with the dialog text.
  197. - **End-to-end cancellation.** `Ctrl+C` propagates through the entire chain (MCP → bridge → extension → Chrome).
  198. - **Sleep/wake recovery.** After a laptop sleep cycle, byob resets its debug sessions so the next call starts clean.
  199. - **Tested end to end** on Chrome for Testing: `BYOB_E2E=1 bun test e2e` (see [CONTRIBUTING](CONTRIBUTING.md)).
  200. ---
  201. ## Security
  202. - `browser_evaluate` (and `browser_wait`'s `fn`) are **off by default** — enable with `BYOB_ALLOW_EVAL=1`. Every call is audit-logged.
  203. - `chrome://`, `file://`, Google/MS/Apple login pages are blocked by default.
  204. - **Per-site allow/deny lists**, set by you — never by the agent:
  205. ```sh
  206. bun run policy --deny "**.chase.com" "mail.proton.me" # never touch these
  207. bun run policy --allow "**.github.com" # or: only these
  208. bun run policy --clear-allow --clear-deny # reset
  209. bun run policy --allow-file on # permit file:// URLs
  210. ```
  211. 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 to a tab, so it covers **every** tool.
  212. - **JS dialogs are never auto-accepted**; a confirm stays open until the agent answers it explicitly.
  213. - **Credential fields are redacted.** Values in password / OTP / card / email inputs are never sent to the model; they surface as `[redacted]`.
  214. - Each install gets a unique extension key — no collisions.
  215. - Socket files are `0600`, dirs are `0700`. Other users can't see them.
  216. - **Zero outbound network traffic.** No analytics, no pings, no crash reports.
  217. - Chrome displays a "byob is debugging this browser" banner on active tabs. This is a Chrome security feature and cannot be suppressed.
  218. ---
  219. ## Troubleshooting
  220. | Symptom | Cause | Fix |
  221. |---|---|---|
  222. | `No live bridge` | Chrome not running or extension disabled | Check `chrome://extensions` |
  223. | `cdp_attach_failed` | DevTools open on that tab | Close DevTools |
  224. | `url_forbidden` | Blocked by your site policy | `bun run policy` |
  225. | `stale_ref` | The page navigated since the snapshot | Snapshot again |
  226. | `element_covered` | A banner / modal is on top | Close it, or `force:true` |
  227. | `extension_not_connected` | Extension lost connection | Reload at `chrome://extensions` |
  228. | Nothing works after install | Chrome was not fully restarted | Quit Chrome completely (`⌘Q`) and reopen |
  229. Run `bun run doctor` for detailed diagnostics on which step failed.
  230. ---
  231. ## Platform notes
  232. | Platform | Auto | Manual |
  233. |---|---|---|
  234. | **macOS** | Auto-registers selected MCP tools | Open `chrome://extensions` and load the unpacked extension |
  235. | **Windows** | Same + writes Native Messaging host to registry | Same as macOS |
  236. | **Linux** | Auto-registers selected MCP tools | Same as macOS |
  237. ---
  238. ## More
  239. - [Changelog](CHANGELOG.md)
  240. - [Contributing](CONTRIBUTING.md)
  241. - [Manual release checklist](docs/e2e-checklist.md)
  242. MIT licensed. byob has broad access to your browser — only use it on machines and accounts you own.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.