bb-sites: community adapters that turn logged in websites into CLI commands

Every adapter is a function that runs in your own browser session

bb-sites is described as community site adapters for bb-browser, turning websites into CLI commands, and the framing line is that each site adapter is a JavaScript function that runs inside your browser via bb-browser eval.

That single sentence is the whole architecture. The browser is already logged in, and the README is explicit about what that means: no API keys, no cookie extraction, no anti-bot bypass. The adapter is a piece of code you evaluate in a page you have already authenticated to, and it reads the page the same way the site itself would.

The consequence is worth spelling out. Because the code runs in the page, it can use the site's own internal APIs, the store state the frontend keeps, and the same endpoints the page uses, rather than trying to reverse engineer a public interface. That is why the README notes that the Xiaohongshu adapters use a mix of current Pinia store state, in-page routing and SSR state parsing, in order to avoid relying on stale XHR paths that no longer fire consistently on the live site.

That last detail is the clearest signal about what this project is. A site that changes its internal request paths breaks adapters, and the fix is to read state a different way. A site adapter here is a maintenance liability as much as a feature, and the repository is honest about that.

The catalogue is the other headline. The README states 102 adapters across 36 platforms, and the top level directory listing backs it up with one directory per platform, from 36kr/ and arxiv/ through weibo/, xiaohongshu/ and zhihu/. The primary language is JavaScript, the default branch is main, and the last push was on 2026-08-18 with no GitHub releases.

The command shape is platform/command, and the same one everywhere

Every adapter is addressed the same way, which is what makes the catalogue usable without reading a document per site.

The quick start shows the four operations.

bb-browser site update                     # install/update site adapters
bb-browser site list                       # list available commands
bb-browser site reddit/me                  # run a command
bb-browser site reddit/thread <url>        # run with args

So the first argument is the site and the second is the action within it, and extra arguments are passed through to the site command. The site update step pulls the adapters into the local bb-browser installation, and site list shows what is available.

The usage examples in the README show the same shape across very different data, which is the point.

# Search the web
bb-browser site google/search "bb-browser"

# Tech research
bb-browser site github/repo epiral/bb-browser
bb-browser site arxiv/search "large language model"

There is also a category of adapters that create things rather than read them. GitHub carries github/issue-create, github/pr-create and github/fork alongside the read commands, and the Xiaohongshu group includes note, comments and user_posts. That is worth noting for anyone evaluating the project, because a catalogue that can write to a site is a different risk profile from one that only reads, even though the execution model is identical.

The README also carries a bilingual structure, with English and Chinese versions of the documentation linked at the top, and there is a SKILL.md at the root of the repository, which suggests the catalogue is meant to be usable by an agent as well as by a person.

The catalogue is organised by platform, and the Chinese platforms are the deepest part

The adapter tables are grouped by category, and the distribution across them is informative.

Search engines cover Google, Baidu, Bing, DuckDuckGo and Sogou, including a Sogou WeChat article search. News and media covers BBC with an RSS variant, Reuters, Toutiao search and trending, and Eastmoney financial news.

The social media group is the widest. Twitter and X have user profile, tweet threads, search, timeline and notifications. Reddit has user info, posts, discussion trees and comment chains. Weibo has seven commands covering profile, trending, timeline, posts and comments, and there is a separate Mobile Weibo group of seven more, described as mobile-optimized and built on resilient JSON APIs.

The tech and developer group is the one a working programmer would use most. GitHub, Hacker News with a post and comment tree, Stack Overflow, npm, PyPI, arXiv, Dev.to, V2EX, plus CSDN and cnblogs for Chinese technical writing.

Entertainment is extensive: nine Bilibili adapters, six YouTube commands including transcripts, six Douban commands with a Top 250 list and reviews, IMDb, Genius and Qidian.

There are also jobs, finance, knowledge, lifestyle and a social apps group, which is where Xiaohongshu and Jike live.

Two regional observations fall out of this. The Chinese platforms are covered far more deeply than the Western ones, with seven commands for Weibo and another seven for Mobile Weibo, nine for Bilibili and six for Douban against a single command each for IMDb and Genius. And the presence of V2EX, CSDN, cnblogs, 36kr, smzdm, linuxdo, sohu, xueqiu and xiaoyuzhoufm in the directory listing but not in the visible tables suggests the catalogue is wider than the README shows.

The one explicit note about a specific platform is instructive. It says to open a logged in xiaohongshu.com tab before running those commands, because the adapters read the current user store rather than assuming a path.

A design document and a skill file sit next to the adapters

The root of the repository holds more than adapters, and the extra files are the interesting part for anyone thinking about how this kind of catalogue should be structured.

There is a DESIGN.md, a SKILL.md, a CONTRIBUTING.md, and two README files, one in English and one in Chinese. There are also fixtures/ and test/ directories, and a .github directory.

The presence of a fixtures directory and a test directory next to fifty platform directories is a deliberate answer to the fragility problem. If each adapter has a recorded fixture and a test, then a site change shows up as a failing test rather than as a wrong answer printed to your terminal, which is the failure mode you would otherwise have to discover by hand.

A DESIGN.md next to the adapters suggests the author has written down the contract an adapter is expected to follow, which matters for a catalogue that a hundred and more people contribute to. And a SKILL.md is the format that agent tools read, so the catalogue is exposed to agents directly, not only through the bb-browser command line.

The practical advice that follows from all this is simple. If you want to use one adapter, read the platform directory and its fixtures before you trust it in a script. The value of the catalogue is that you do not have to write the DOM spelunking yourself; the risk is that the same fragility is now someone else's maintenance problem, and the fixtures are how you check it still works.

Where bb-sites is the wrong tool

The first wrong-tool case is a scheduled or headless job. The model assumes a browser with a live, logged in session that someone opened. That is fine for an interactive terminal workflow, and it is the wrong shape for a cron job on a server, where the session would have to be established and kept valid programmatically, which is exactly the cookie handling the project says it does not do.

The second case is a project that needs a supported contract. There are no GitHub releases, the catalogue is community contributed, and the last push was on 2026-08-18. An adapter for a site that changed its request paths last month may simply be broken today, and the only way to find out is to run it.

The third case is a write-heavy workflow against an account you care about. Because adapters can create issues, pull requests, forks, posts and comments, the same tool that reads your timeline can also post to it. The execution model gives no isolation between the two, and the session carries whatever permissions the logged in account has.

There is a fourth case, and it is not a technical one. The adapters read content behind a login, and a site whose terms forbid automated access is a site where running an adapter against it is a decision for you rather than for the tool. The README states that there is no anti-bot bypass, which is a good sign about the project's intent, and it does not change who is responsible for how the automation is used.

One limitation is structural and worth knowing: the coverage is uneven by design, following where the author and contributors spend time rather than where the demand is. The command list is the true API surface, and if a site you care about is missing, the contribution path is a directory with a function in it, following the pattern of the existing adapters.

Editorial conclusion

bb-sites suits someone who wants to script a workflow against sites they are already logged into, particularly across the Chinese platforms where no public API exists, and the per-site directories make it easy to read one adapter before trusting it. It does not suit a scheduled service on a headless server, since the whole model assumes a browser with a live session, and it does not suit anyone who needs a supported, stable interface, since the adapters are community contributed and the repository has no releases. Before adopting, read the DESIGN.md and SKILL.md files that sit at the root, and open the fixtures/ and test/ directories to see how an adapter is expected to behave.

Frequently asked questions

Official sources

1. epiral/bb-sites on GitHub
2. Issues
3. README