byob

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

English · 中文

What can I do with this?

You ask Claude (or Cursor / Cline) to do something on the web. byob makes it happen in your real Chrome — the one where you're already logged into Twitter, GitHub, Gmail, your work tools, everything.

A few things people actually ask:

"read my Twitter timeline and tell me the top 5 posts"

byob opens a tab, scrolls through it, hands the text back. Because it's your real browser, your tweets show up — no fake account, no copy-pasting cookies, no captchas.

"google 'mcp protocol spec', click the first result, and read the page"

byob goes to google.com, types your search, hits Enter, waits for results, clicks the first link, reads it. All in one prompt.

"give me my github session cookie so I can use curl in a script"

byob hands you the cookie. Now curl https://github.com/... works just like you're logged in.

"take a screenshot of example.com"

byob saves a PNG to disk and tells Claude where it is. (Doesn't dump base64 into Claude's context — that would burn through your tokens.)

"open my Gmail tab and tell me how many unread"

Cloud headless browsers can't see your Gmail because they're not logged in. byob can — because it IS your browser.

Why not just `WebFetch` or Puppeteer?

	WebFetch	Headless Puppeteer	byob
Sees pages that need login	❌	⚠️ have to copy cookies in	✅ already logged in
Gets past "are you a bot?" checks	❌	❌	✅ it really is a human's browser
Setup time	0	hours	5 min
Costs cloud money	nope	yes	nope

5-minute install

git clone https://github.com/<you>/byob ~/code/byob
cd ~/code/byob && bun install

# one command does everything: makes a key, builds the extension,
# tells Chrome about it
( cd packages/bridge && bun run dev:cli install --dev )

# load the extension in Chrome:
#   chrome://extensions  →  Developer mode  →  Load unpacked
#   pick: packages/extension/.output/chrome-mv3
# then fully quit Chrome (⌘Q) and open it again

# check it works
( cd packages/bridge && bun run dev:cli doctor )
# four green ✓ means you're good

# tell Claude Code about byob
claude mcp add byob -s user -- /Users/$USER/code/byob/packages/mcp-server/node_modules/.bin/tsx /Users/$USER/code/byob/packages/mcp-server/bin/byob-mcp.ts

Open a fresh Claude Code session and say "use byob to ...".

The 10 things byob can do

Tool	What it does
📖 `browser_read`	Open a page, scroll through it, read everything
📸 `browser_screenshot`	Take a screenshot, save to disk
🖱️ `browser_click`	Click a button or link
⌨️ `browser_type`	Type into a text box (and hit Enter if you want)
🍪 `browser_get_cookies`	Grab the cookies for a site so you can `curl` it later
🚀 `browser_navigate`	Go to a URL in a new or existing tab
⏳ `browser_wait_for`	Wait until something appears on the page
🗂️ `browser_list_tabs`	Show me all my open tabs
🎯 `browser_switch_tab`	Switch to a specific tab
⚡ `browser_eval`	Run any JavaScript on the page (off by default — see Security)

Full input/output shapes: shared/src/schemas.ts.

How it actually works

Claude Code  ─→  byob-mcp  ─→  byob-bridge  ─→  Chrome extension  ─→  your Chrome tab

Four hops, all on your laptop. Nothing leaves your machine. Close Chrome and everything quits — no background processes hanging around.

Stuff to know about safety

🔒 browser_eval (run JS) is off by default — even Claude doesn't see it exists. Turn it on by setting BYOB_ALLOW_EVAL=1 when you register the MCP. When it's on, every call gets logged and pops a Chrome notification.
🚫 Some sites are blocked by default — chrome://, file://, your Google/Microsoft/Apple login pages. So Claude can't accidentally read your password manager or /etc/passwd.
🔑 You get your own extension key — when you install, byob makes a key just for you. Two people running byob get two different extension IDs, no clash.
📁 Files are private — sockets are 0600, folders are 0700. Other users on your computer can't read them.
📡 byob never phones home — no analytics, no auto-update pings, no crash reports. Zero outbound traffic.
⚠️ Chrome will show "byob is debugging this tab" at the top of the page. There is no way to hide it — that's a Chrome safety thing, not a byob bug. Every tool that uses Chrome's debugger has the same banner.

Day-to-day commands

byob install     # set everything up (or fix it after Chrome breaks)
byob doctor      # check what's working and what's not
byob bridges     # show me the running bridges
byob logs [-f]   # tail the log
byob uninstall   # nuke the launcher and manifests

Want to know more?

Design notes — how byob works under the hood and why
Changelog — what's done and what's coming
Contributing — how to send a PR
Test checklist — things to try before each release

Something's broken — what do I do?

What you see	What's probably wrong
`No live bridge`	Chrome isn't open, or the byob extension is disabled. Check `chrome://extensions`.
`cdp_attach_failed`	DevTools (F12) is open on that tab. Close it.
`url_forbidden` on a normal URL	The URL is on the default blocklist (see Safety). Use a different tab.
`extension_not_connected`	Reload the byob extension at `chrome://extensions`.
Just installed but nothing works	Fully quit Chrome (⌘Q) and reopen. Chrome only checks for the byob bridge when it starts up.

Still stuck? Run byob doctor — it tells you exactly which step is broken.

MIT licensed. byob has a lot of access to your browser — only run it on machines and accounts you own.