byob (Bring Your Own Browser)

What does this agent do, and when should you use it?

byob is a local MCP server that connects AI coding tools (Claude Code, Cursor, Cline, Windsurf, Codex CLI and other MCP clients) to your everyday Chrome. It is built from three pieces: the stdio MCP server byob-mcp, a local byob-bridge process reached over a Unix socket, and an MV3 Chrome extension that talks to the bridge via Native Messaging and drives tabs through the Chrome DevTools Protocol. Version 0.5 ships 25 tools spanning snapshots, finding, clicking, typing, key presses, scrolling, drag-and-drop, file upload, content extraction, screenshots/PDF, tab management, console and network capture, cookies and storage, dialogs, device emulation, clipboard and batched steps. Because it uses your real logged-in browser, it can see authenticated pages and usually passes bot detection, at the cost of a local extension install, a manual unpacked load and a full Chrome restart. All traffic stays on the machine, and page scripts run in an isolated world so sites never see byob globals or data attributes.

The AI client calls byob-mcp over stdio; the request goes to byob-bridge, across Native Messaging into the Chrome extension, which executes it in your tab via the Chrome DevTools Protocol. Elements are targeted by snapshot refs such as [ref=e12], CSS selectors, or x/y coordinates. browser_snapshot returns an accessibility outline with refs (interactive-only, diff, scoped, iframes inlined), and browser_find locates by role+name, text, label, placeholder or testId and can click, fill or check in the same call. browser_click, browser_type, browser_press_key, browser_hover, browser_select, browser_scroll, browser_drag and browser_upload_file emit real mouse and keyboard events and auto-wait for elements to be attached, visible, stable, enabled and on top, then report navigation, new tabs and JS dialogs. browser_read emits text, markdown reader mode, html, links or tables; browser_screenshot returns viewport, full page, element or clipped images to the model and can produce PDFs. browser_network records traffic (summary, JSON, HAR) or blocks, mocks and modifies requests; browser_storage gets, sets and clears cookies and local/session storage; browser_emulate switches device, dark mode, geolocation, timezone, locale, offline and headers. browser_evaluate runs page JavaScript only when BYOB_ALLOW_EVAL=1 is set, and every call is audit-logged. browser_batch bundles many steps into one round trip.

1. A developer asks Claude Code to read their logged-in GitHub or Gmail tab and report unread counts before continuing to code
2. Authenticated data gathering: have the agent read a Twitter/X timeline and summarize the top posts, or search, click the first result and read the page
3. Front-end debugging on a real session: export a HAR with browser_network, check errors with browser_console, inspect box model and Web Vitals with browser_inspect
4. Filling and submitting a multi-field form via browser_batch, then screenshotting the result to confirm
5. Producing deliverables like a full-page screenshot or PDF of a site for a report
6. Reusing an existing session cookie for script verification, as in the README example of grabbing a GitHub session cookie to curl with

How do you install or deploy this agent?

Prerequisites: Node.js ≥ 20, bun, Chrome/Edge/Brave, and any MCP-compatible AI tool. On Windows, run the one-liner from Git Bash or MSYS2.

The recommended install script checks prerequisites, clones the repo, builds everything and walks through MCP registration interactively (it offers to install bun with the native installer if missing). Set BYOB_INSTALL_DIR to change the install location (default ~/byob).

curl -fsSL https://raw.githubusercontent.com/wxtsky/byob/main/install.sh | bash

Manual install instead:

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

setup asks for output language (English / 中文), generates a unique extension key, builds the extension, writes the config that lets Chrome talk to byob, and lets you multi-select your AI tools (Claude Code gets the bundled plugin; others get MCP config). Three manual steps remain. First, open chrome://extensions, enable Developer mode, click Load unpacked and pick the printed folder, e.g. /your/path/to/byob/packages/extension/output/chrome-mv3. Second, quit Chrome completely (⌘Q on macOS) and reopen it, since Chrome reads Native Messaging config only at startup. Third, wait for setup to print ✓ bridge online, or check later:

bun run doctor

If you skipped the registration prompt, register MCP manually, for example with Claude Code:

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

Or install the Claude Code plugin:

claude plugin marketplace add wxtsky/byob
claude plugin install byob@byob --scope user

How do you use this agent?

Once the bridge is online, start a new session in your AI tool and ask in natural language, e.g. "use byob to read my Twitter timeline and summarize the top 5 posts".

Set per-site policy yourself (the agent cannot change it):

bun run policy --deny "**.chase.com" "mail.proton.me"
bun run policy --allow "**.github.com"
bun run policy --clear-allow --clear-deny
bun run policy --allow-file on

To let the agent run page JavaScript, opt in explicitly:

claude mcp add byob -s user -e BYOB_ALLOW_EVAL=1 -- /path/to/tsx /path/to/byob-mcp.ts

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

Everyday maintenance commands, run from the repo root:

bun run doctor     # diagnose which step failed
bun run bridges    # list running bridge processes
bun run logs       # tail the bridge log
bun run unsetup    # remove everything

Common errors: No live bridge (Chrome not running or extension disabled), cdp_attach_failed (DevTools open on that tab), url_forbidden (blocked by your site policy), stale_ref (page navigated; snapshot again), element_covered (a banner or modal is on top; close it or use force:true).

What are this agent's strengths and limitations?

How does this agent compare with similar options?

Key facts side by side with the most closely related agents.

How does FollowAgents rate this agent?

FAQ