[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-2918":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":14,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":18,"compositeScore":19,"rankGlobal":10,"rankLanguage":10,"license":20,"archived":21,"fork":21,"defaultBranch":22,"hasWiki":23,"hasPages":21,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":37,"readmeContent":38,"aiSummary":39,"trendingCount":15,"starSnapshotCount":15,"syncStatus":16,"lastSyncTime":40,"discoverSource":41},2918,"byob","wxtsky\u002Fbyob","wxtsky","Bring Your Own Browser — let your AI agent use the Chrome you already have open","https:\u002F\u002Fgithub.com\u002Fwxtsky\u002Fbyob",null,"TypeScript",127,15,1,0,2,9,3,3.61,"MIT License",false,"main",true,[25,26,27,28,29,30,31,32,33,34,35,36],"ai-agent","browser-automation","bun","chrome-debugger","chrome-extension","claude-code","cursor","mcp","mcp-server","native-messaging","typescript","wxt","2026-06-12 02:00:44","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"assets\u002Flogo.svg\" alt=\"byob\" width=\"120\"\u002F>\n\n# byob\n\n**Bring Your Own Browser** — let your AI assistant use the Chrome you already have open.\n\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-22c55e.svg)](LICENSE) [![MCP](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-stdio-0a0a0a.svg)](https:\u002F\u002Fmodelcontextprotocol.io) [![Chrome MV3](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FChrome-MV3-f59e0b.svg)](https:\u002F\u002Fdeveloper.chrome.com\u002Fdocs\u002Fextensions\u002Fmv3\u002Fintro\u002F) [![v0.3](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fv0.3-ready-22c55e.svg)](CHANGELOG.md)\n\n**English** · [中文](README.zh-CN.md)\n\n\u003C\u002Fdiv>\n\n---\n\nbyob 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.\n\n```\n\"read my Twitter timeline and summarize the top 5 posts\"\n\"google 'mcp protocol spec', click the first result, read the page\"\n\"take a screenshot of example.com\"\n\"grab my GitHub session cookie so I can curl with it\"\n\"open my Gmail tab and tell me how many unread\"\n```\n\n|  | WebFetch | Headless Puppeteer | **byob** |\n|---|:-:|:-:|:-:|\n| Sees logged-in pages | ❌ | ⚠️ manual cookie copy | ✅ already logged in |\n| Passes bot detection | ❌ | ❌ | ✅ real human browser |\n| Setup time | 0 | hours | **~5 min** |\n| Cloud cost | free | $$ | free |\n\n---\n\n## Install\n\n### Quick install (recommended)\n\n```sh\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002Fwxtsky\u002Fbyob\u002Fmain\u002Finstall.sh | bash\n```\n\nThe 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.\n\n> Set `BYOB_INSTALL_DIR` to change the install location (default: `~\u002Fbyob`).\n\n### Manual install\n\n\u003Cdetails>\n\u003Csummary>Prefer to do it yourself?\u003C\u002Fsummary>\n\nRequires **Node.js ≥ 20**, **bun**, **Chrome**, and any MCP-compatible AI tool.\n\n```sh\ngit clone https:\u002F\u002Fgithub.com\u002Fwxtsky\u002Fbyob\ncd byob\nbun install\nbun run setup\n```\n\n\u003C\u002Fdetails>\n\n`bun run setup` walks through the install interactively:\n\n1. Pick output language (English \u002F 中文)\n2. Generates a unique extension key for you\n3. Builds the Chrome extension\n4. Writes the config that lets Chrome talk to byob\n5. 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)\n\nAfter the script finishes, three manual steps remain:\n\n### Step 2 — Load extension in Chrome\n\nOpen `chrome:\u002F\u002Fextensions` in Chrome.\n\n1. Top-right → turn ON **Developer mode**\n2. Top-left → click **Load unpacked**\n3. Select the folder printed in your terminal, something like:\n   ```\n   \u002Fyour\u002Fpath\u002Fto\u002Fbyob\u002Fpackages\u002Fextension\u002Foutput\u002Fchrome-mv3\n   ```\n\n### Step 3 — Restart Chrome\n\n**Quit Chrome completely** (`⌘Q` on Mac \u002F close all windows on Windows), then reopen.\n\n> Closing a single tab or window is not sufficient — Chrome only reads the Native Messaging config at startup.\n\n### Step 4 — (Reference) Manual MCP registration\n\nThe 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:\n\n\u003Cdetails open>\n\u003Csummary>\u003Cb>Claude Code\u003C\u002Fb>\u003C\u002Fsummary>\n\n```sh\nclaude mcp add byob -s user -- \u002Fpath\u002Fto\u002Ftsx \u002Fpath\u002Fto\u002Fbyob-mcp.ts\n```\n\nTo enable `browser_eval`, add `-e BYOB_ALLOW_EVAL=1` after `-s user`.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Codex CLI\u003C\u002Fb>\u003C\u002Fsummary>\n\n```sh\ncodex mcp add byob -- \u002Fpath\u002Fto\u002Ftsx \u002Fpath\u002Fto\u002Fbyob-mcp.ts\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Cursor\u003C\u002Fb>\u003C\u002Fsummary>\n\nAdd to `.cursor\u002Fmcp.json` (project) or `~\u002F.cursor\u002Fmcp.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"byob\": {\n      \"command\": \"\u002Fpath\u002Fto\u002Ftsx\",\n      \"args\": [\"\u002Fpath\u002Fto\u002Fbyob-mcp.ts\"]\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Windsurf\u003C\u002Fb>\u003C\u002Fsummary>\n\nAdd to `~\u002F.codeium\u002Fwindsurf\u002Fmcp_config.json` (same JSON format as Cursor):\n\n```json\n{\n  \"mcpServers\": {\n    \"byob\": {\n      \"command\": \"\u002Fpath\u002Fto\u002Ftsx\",\n      \"args\": [\"\u002Fpath\u002Fto\u002Fbyob-mcp.ts\"]\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cb>Cline (VS Code)\u003C\u002Fb>\u003C\u002Fsummary>\n\nOpen Cline sidebar → MCP Servers → Configure, then add (same JSON format):\n\n```json\n{\n  \"mcpServers\": {\n    \"byob\": {\n      \"command\": \"\u002Fpath\u002Fto\u002Ftsx\",\n      \"args\": [\"\u002Fpath\u002Fto\u002Fbyob-mcp.ts\"]\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n> The actual paths are printed by the setup script. The examples above use shortened paths for readability.  \n> To enable `browser_eval`, add `\"env\": { \"BYOB_ALLOW_EVAL\": \"1\" }` to the config (or `-e BYOB_ALLOW_EVAL=1` for CLI tools).\n\n### Step 5 — Wait for setup to confirm the bridge is online\n\nAfter 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 ...\"_.\n\nIf you exited setup early with Ctrl+C, or want to check the state later:\n\n```sh\nbun run doctor\n```\n\n`bun run doctor` prints actionable fixes under every `✗` (e.g. \"⌘Q-restart Chrome\", \"extension ID mismatch\", etc.).\n\n---\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `browser_read` | Open a page, scroll through, read all text |\n| `browser_read_markdown` | Same, returns clean markdown (no nav\u002Fads) |\n| `browser_extract_table` | Pull `\u003Ctable>` elements as JSON |\n| `browser_get_console_logs` | Snapshot console.log \u002F warn \u002F error |\n| `browser_start_record_network` | Start recording HTTP + WebSocket traffic |\n| `browser_stop_record_network` | Stop recording, export JSON or HAR |\n| `browser_screenshot` | Screenshot → saved to disk |\n| `browser_download_images` | Download all images from a page |\n| `browser_click` | Click a button or link |\n| `browser_type` | Type into an input (optionally press Enter) |\n| `browser_press_key` | Send a keyboard key (Enter, Escape, F5, ArrowDown, ...) |\n| `browser_hover` | Hover the mouse over an element to trigger tooltips\u002Fmenus |\n| `browser_select` | Choose an option in a native `\u003Cselect>` |\n| `browser_scroll` | Scroll to top\u002Fbottom, an element, or a Y coordinate |\n| `browser_get_html` | Get raw HTML of an element or the whole page |\n| `browser_get_cookies` | Export cookies for `curl` \u002F scripts |\n| `browser_navigate` | Open a URL in a new or existing tab |\n| `browser_go_back` | Go back one step in browser history |\n| `browser_go_forward` | Go forward one step in browser history |\n| `browser_wait_for` | Wait for an element to appear |\n| `browser_list_tabs` | List all open tabs |\n| `browser_switch_tab` | Switch to a tab |\n| `browser_close_tab` | Close a tab by tabId |\n| `browser_eval` | Run JavaScript on the page (off by default) |\n| `browser_set_cookies` | Write a cookie via `chrome.cookies.set` (CHIPS-aware). |\n| `browser_print_pdf` | Save current page as PDF (default `~\u002F.byob\u002Fpdfs\u002F`). |\n| `browser_get_storage` | Read `localStorage` \u002F `sessionStorage` for an origin. |\n| `browser_get_performance` | Page Web Vitals + navigation timing. |\n| `browser_upload_file` | Upload local files to `\u003Cinput type=\"file\">`. |\n| `browser_intercept_start` | Start a stateful request-interception session. |\n| `browser_intercept_stop` | Stop a `browser_intercept_start` session and return hit stats. |\n| `browser_drag` | Drag the mouse from one point to another (linear interpolation). |\n| `browser_emulate_device` | Emulate mobile\u002Ftablet viewport \u002F DPR \u002F touch \u002F UA. |\n\n17 of these tools support `framePath` to reach into nested iframes (including cross-origin).\n\nFull schemas: [`shared\u002Fsrc\u002Fschemas.ts`](shared\u002Fsrc\u002Fschemas.ts)\n\n---\n\n## How it works\n\n```\nAI tool → byob-mcp → byob-bridge → Chrome extension → your tab\n         (stdio)    (Unix socket) (Native Messaging) (Chrome DevTools Protocol)\n```\n\nAll communication stays local. No data leaves your machine. When Chrome closes, all byob processes exit automatically.\n\n---\n\n## Everyday commands\n\n```sh\nbun run setup      # install or re-install\nbun run doctor     # check what's working\nbun run bridges    # list running bridge processes\nbun run logs       # tail the bridge log\nbun run unsetup    # remove everything\n```\n\nAll run from the byob repo root.\n\n---\n\n## Reliability\n\n- **End-to-end cancellation.** `Ctrl+C` propagates through the entire chain (MCP → bridge → extension → Chrome), cleanly detaching all debug sessions.\n- **DevTools conflict handling.** If DevTools is open on a tab, `browser_eval` automatically falls back to `chrome.scripting.executeScript`.\n- **Sleep\u002Fwake recovery.** After a laptop sleep cycle, byob resets all debug sessions so the next call starts from a clean state.\n\n---\n\n## Security\n\n- `browser_eval` is **off by default** — enable with `BYOB_ALLOW_EVAL=1`. Every call logs + notifies.\n- `chrome:\u002F\u002F`, `file:\u002F\u002F`, Google\u002FMS\u002FApple login pages are blocked by default.\n- Each install gets a unique extension key — no collisions.\n- Socket files are `0600`, dirs are `0700`. Other users can't see them.\n- **Zero outbound network traffic.** No analytics, no pings, no crash reports.\n- Chrome displays a \"byob is debugging this browser\" banner on active tabs. This is a Chrome security feature and cannot be suppressed.\n\n---\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| `No live bridge` | Chrome not running or extension disabled | Check `chrome:\u002F\u002Fextensions` |\n| `cdp_attach_failed` | DevTools open on that tab | Close DevTools |\n| `url_forbidden` | URL on the blocklist | See Security section |\n| `extension_not_connected` | Extension lost connection | Reload at `chrome:\u002F\u002Fextensions` |\n| Nothing works after install | Chrome was not fully restarted | Quit Chrome completely (`⌘Q`) and reopen |\n\nRun `bun run doctor` for detailed diagnostics on which step failed.\n\n---\n\n## Platform notes\n\n| Platform | Auto | Manual |\n|---|---|---|\n| **macOS** | Auto-registers selected MCP tools | Open `chrome:\u002F\u002Fextensions` and load the unpacked extension |\n| **Windows** | Same + writes Native Messaging host to registry | Same as macOS |\n| **Linux** | Auto-registers selected MCP tools | Same as macOS |\n\n---\n\n## More\n\n- [Changelog](CHANGELOG.md)\n- [Contributing](CONTRIBUTING.md)\n- [Design notes](docs\u002Fsuperpowers\u002Fspecs\u002F2026-04-25-byob-design.md)\n- [Test checklist](docs\u002Fe2e-checklist.md)\n\nMIT licensed. byob has broad access to your browser — only use it on machines and accounts you own.\n","byob 是一个本地 MCP 服务器，允许 AI 编码工具直接控制你已经打开的 Chrome 浏览器。其核心功能包括通过真实浏览器执行自动化任务如读取网页内容、截图等，能够绕过登录验证和反爬虫机制。项目使用 TypeScript 开发，并支持 MCP 协议与多种 AI 工具集成。适用于需要在已登录状态下进行网页操作的场景，例如抓取个人数据或执行特定任务，相比传统的无头浏览器方案，设置简单快捷且成本更低。","2026-06-11 02:51:41","CREATED_QUERY"]