bb-browser: a Chrome CLI and MCP server that reuses your existing login sessions

The problem bb-browser solves: authenticated pages without an API

Most sites an agent would want to read from do not publish an API. The README puts the figure at "99% of websites", and the practical consequence is that agents get files, a terminal, and a handful of keyed APIs. Everything behind a login is out of reach unless you reimplement authentication.

bb-browser takes the opposite route. Rather than asking sites for machine interfaces, it lets the agent use the human interface. The README's framing is that the adapter runs eval inside your browser tab, calls fetch() with your cookies, or invokes the page's own webpack modules, and that "the website thinks it's you. Because it is you." The target user is someone running an agent framework (Claude Code, Cursor, Codex are named) who wants that agent to read Twitter, Zhihu, arXiv or a stock quote without provisioning credentials for each one.

The comparison table in the README makes the positioning explicit. Playwright and Selenium run a headless, isolated browser with no login state; scraping libraries extract cookies or reverse engineer auth; bb-browser uses the Chrome you are already signed into. That difference is the whole product.

How the CLI, daemon and CDP chain fit together

The architecture diagram in the README shows three hops. The agent talks to the bb-browser CLI over stdio (as a CLI or as an MCP server). The CLI talks to a local daemon over HTTP. The daemon talks to your real browser over a CDP WebSocket.

That split matters for how you deploy it. The daemon is a separate process with its own binary entry point: package.json declares two bins, bb-browser and bb-browser-daemon, both built from dist. The daemon binds to 127.0.0.1:19824 by default, and the README documents a --host flag for changing that, with 127.0.0.1 given as the fix for macOS IPv6 issues and 0.0.0.0 described as listening on all interfaces for Tailscale or ZeroTier remote access.

Site commands are adapters, not built-in scrapers. The README states they are community-driven via the bb-sites repository, one JS file per command, and that bb-browser site update pulls them. The adapter tiers described in the README are a useful mental model for how much can go wrong: tier 1 uses cookies and a direct fetch (Reddit, GitHub, V2EX), tier 2 adds a bearer token and CSRF token (Twitter, Zhihu), tier 3 injects into webpack or a Pinia store (Twitter search, Xiaohongshu). Tier 3 adapters are coupled to a site's internal module layout, which is exactly the kind of thing that changes without notice.

Installing bb-browser and running a first site command

The README gives a global npm install and requires Node.js 18 or newer, which package.json confirms with an engines field of node >=18.0.0. The published package name is bb-browser.

npm install -g bb-browser

After installing, pull the community adapters and check which ones match your browsing habits before running anything:

bb-browser site update
bb-browser site recommend
bb-browser site zhihu/hot

The README presents these three lines as the quick start: update fetches adapters, recommend lists the ones that fit how you already browse, and the third line is an actual command. Output is structured JSON, so the next step is usually filtering it inline rather than piping through another tool:

bb-browser site xueqiu/hot-stock 5 --jq '.items[] | {name, changePercent}'

The README shows this example returning objects with name and changePercent keys. To find out what arguments an adapter takes before you call it, the README documents bb-browser site info <adapter>, which reports args, an example, and the domain. If you use OpenClaw, the README says bb-browser runs through its built-in browser with a --openclaw flag and no Chrome extension or daemon. For Claude Code or Cursor, the README gives an MCP configuration that runs npx -y bb-browser --mcp.

bb-browser is also a general Chrome automation tool

The site adapters get the attention, but the README documents a second, lower-level surface that does not depend on any adapter existing. You can open a URL, take an accessibility snapshot, click and fill by reference, evaluate JavaScript, fetch with your session cookies, capture network traffic with bodies, and take screenshots.

bb-browser open https://example.com
bb-browser snapshot -i
bb-browser click @3
bb-browser fill @5 "hello"
bb-browser eval "document.title"
bb-browser fetch URL --json
bb-browser network requests --with-body --json

The README states that all commands support --json output, --jq for inline filtering, and --tab <id> for concurrent multi-tab work. This is the part of the project that ages best. Adapters break when a site changes; open, snapshot, click and eval break when the browser changes, which is a much slower-moving target. If you are evaluating bb-browser, this layer is worth more attention than the adapter count. It is also what the README's adapter-authoring workflow is built on: the guide tells an agent to reverse-engineer an API using network --with-body, write the adapter, test it, and open a PR.

The adapter dependency is the real limitation

bb-browser itself is a thin transport. The value sits in bb-sites, a separate repository, and the README is direct that adapters are community-driven. That has three consequences worth stating plainly.

First, coverage is uneven by design. The README's platform table lists search engines, social networks, news, dev sites, video, finance, jobs and shopping, with 103 commands across 36 platforms. Nothing in the README says how many of those are tier 1 versus tier 3, and the tier distinction is the difference between an adapter that survives a site redesign and one that does not.

Second, there is no documented fallback when an adapter breaks. The README does not document rollback, pinning an adapter to a version, or a compatibility check beyond bb-browser site update and bb-browser site info. If a tier 3 adapter stops working, the documented path forward is the same one used to create it: the guide, network --with-body, and a rewrite.

Third, the wrong-tool case is clear. If you need unattended, high-volume collection from sites you have no account on, this is not it. The design assumes a logged-in human profile, and the README's own comparison says anti-bot systems see the real user because it is the real user. Running that at volume is a different risk profile than running it interactively.

bb-browser compared with Playwright and Selenium

The README's comparison table is the honest place to start. Playwright and Selenium launch a headless, isolated browser with no login state, so you re-authenticate or script the login flow. bb-browser attaches to your real Chrome, where the login already exists, and the README argues complex auth is handled by the page itself rather than reverse engineered.

The difference in approach shows up in what each tool is good at. Playwright and Selenium are deterministic test harnesses: you control the browser lifecycle, you can run many isolated contexts in parallel, and a failure is reproducible because the environment is defined by your code. bb-browser's environment is your actual profile, with your extensions, your cookies, and your current tab state. That is the source of its advantage and the source of its unpredictability.

There is a cost dimension too. bb-browser's Dockerfile installs Chrome for Testing plus Xvfb, and the comment in that file states headed Chrome is required because --headless=new on Linux lacks full GUI APIs (WebGL, plugins, screen info) that anti-bot systems detect. That is a container image with a virtual framebuffer and a pre-installed viewer binary, which is heavier than a typical Playwright base image. If your workload is a scripted flow against a site you control, Playwright is the simpler answer.

Licence, maintenance and what an upgrade actually costs

The project is MIT licensed, stated in both the README badge and the package.json license field, and the repository ships a LICENSE file. MIT is permissive, so the practical implication for adopters is that you can vendor or modify it. The adapters in bb-sites are a separate repository; the README does not state their licence, so check that before redistributing adapter code.

Maintenance signals: the repository is not archived, and the last push was on 2026-05-29. The most recent release listed is bb-browser-v0.11.6 from 2026-05-11, while package.json on the default branch reads version 0.14.2, so the branch is ahead of the latest tagged release. The project uses release-please and a release-please manifest, which is a conventional automated release setup, and the version numbering is pre-1.0, which is worth reading as a statement about API stability.

Upgrade cost has two parts. Upgrading the CLI is a normal npm global install. Upgrading adapters is bb-browser site update, and that pulls whatever the community has published, with no documented pinning mechanism. For a production agent, that means an adapter that worked yesterday can change today. Budget for that, or pin the adapter files yourself.

Editorial conclusion

Adopt bb-browser when an agent needs authenticated reads from sites you already use in Chrome, and when you accept that adapters live in a separate repository and break when those sites change. Do not adopt it for unattended scraping of sites you have no account on, or for a browser profile you cannot afford to expose to an agent. Verify two things first: that the adapter you need is present in bb-sites, and that you are comfortable with the daemon binding, since the README documents --host 0.0.0.0 as an option for Tailscale or ZeroTier access.

Frequently asked questions

Official sources

1. epiral/bb-browser on GitHub
2. Issues
3. License: MIT
4. README
5. Releases