bb-browser README

The project's README from github.com/epiral/bb-browser. As one markdown file: README.md.

bb-browser

BadBoy Browser

Your browser is the API. No keys. No bots. No scrapers.

npm Node.js License

English · 中文

You're already logged into Twitter, Reddit, YouTube, Zhihu, Bilibili, LinkedIn, GitHub — bb-browser lets AI agents use that directly.

bb-browser site twitter/search "AI agent"       # search tweets
bb-browser site zhihu/hot                        # trending on Zhihu
bb-browser site arxiv/search "transformer"       # search papers
bb-browser site eastmoney/stock "茅台"            # real-time stock quote
bb-browser site boss/search "AI engineer"        # search jobs
bb-browser site wikipedia/summary "Python"       # Wikipedia summary
bb-browser site youtube/transcript VIDEO_ID      # full transcript
bb-browser site stackoverflow/search "async"     # search SO questions

103 commands across 36 platforms. All using your real browser's login state. Full list →

The idea

The internet was built for browsers. AI agents have been trying to access it through APIs — but 99% of websites don't offer one.

bb-browser flips this: instead of forcing websites to provide machine interfaces, let machines use the human interface directly. The adapter runs eval inside your browser tab, calls fetch() with your cookies, or invokes the page's own webpack modules. The website thinks it's you. Because it is you.

Playwright / Selenium Scraping libs bb-browser
Browser Headless, isolated No browser Your real Chrome
Login state None, must re-login Cookie extraction Already there
Anti-bot Detected easily Cat-and-mouse Invisible — it IS the user
Complex auth Can't replicate Reverse engineer Page handles it itself

Quick Start

Install

npm install -g bb-browser

Use

bb-browser site update        # pull community adapters
bb-browser site recommend     # see which adapters match your browsing habits
bb-browser site zhihu/hot     # go

OpenClaw (no extension needed)

If you use OpenClaw, bb-browser runs directly through OpenClaw's built-in browser — no Chrome extension or daemon required:

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

Skill on ClawHub: bb-browser-openclaw

MCP (Claude Code / Cursor)

{
  "mcpServers": {
    "bb-browser": {
      "command": "npx",
      "args": ["-y", "bb-browser", "--mcp"]
    }
  }
}

36 platforms, 103 commands

Community-driven via bb-sites. One JS file per command.

Category Platforms Commands
Search Google, Baidu, Bing, DuckDuckGo, Sogou WeChat search
Social Twitter/X, Reddit, Weibo, Xiaohongshu, Jike, LinkedIn, Hupu search, feed, thread, user, notifications, hot
News BBC, Reuters, 36kr, Toutiao, Eastmoney headlines, search, newsflash, hot
Dev GitHub, StackOverflow, HackerNews, CSDN, cnblogs, V2EX, Dev.to, npm, PyPI, arXiv search, issues, repo, top, thread, package
Video YouTube, Bilibili search, video, transcript, popular, comments, feed
Entertainment Douban, IMDb, Genius, Qidian movie, search, top250
Finance Xueqiu, Eastmoney, Yahoo Finance stock, hot stocks, feed, watchlist, search
Jobs BOSS Zhipin, LinkedIn search, detail, profile
Knowledge Wikipedia, Zhihu, Open Library search, summary, hot, question
Shopping SMZDM search deals
Tools Youdao, GSMArena, Product Hunt, Ctrip translate, phone specs, trending products

10 minutes to add any website

bb-browser guide    # full tutorial

Tell your AI agent: "turn XX website into a CLI". It reads the guide, reverse-engineers the API with network --with-body, writes the adapter, tests it, and submits a PR. All autonomously.

Three tiers of adapter complexity:

Tier Auth method Example Time
1 Cookie (fetch directly) Reddit, GitHub, V2EX ~1 min
2 Bearer + CSRF token Twitter, Zhihu ~3 min
3 Webpack injection / Pinia store Twitter search, Xiaohongshu ~10 min

We tested this: 20 AI agents ran in parallel, each independently reverse-engineered a website and produced a working adapter. The marginal cost of adding a new website to the agent-accessible internet is approaching zero.

What this means for AI agents

Without bb-browser, an AI agent's world is: files + terminal + a few APIs with keys.

With bb-browser: files + terminal + the entire internet.

An agent can now, in under a minute:

# Cross-platform research on any topic
bb-browser site arxiv/search "retrieval augmented generation"
bb-browser site twitter/search "RAG"
bb-browser site github search rag-framework
bb-browser site stackoverflow/search "RAG implementation"
bb-browser site zhihu/search "RAG"
bb-browser site 36kr/newsflash

Six platforms, six dimensions, structured JSON. Faster and broader than any human researcher.

Also a full browser automation tool

bb-browser open https://example.com
bb-browser snapshot -i                # accessibility tree
bb-browser click @3                   # click element
bb-browser fill @5 "hello"            # fill input
bb-browser eval "document.title"      # run JS
bb-browser fetch URL --json           # authenticated fetch
bb-browser network requests --with-body --json  # capture traffic
bb-browser screenshot                 # take screenshot

All commands support --json output, --jq <expr> for inline filtering, and --tab <id> for concurrent multi-tab operations.

bb-browser site xueqiu/hot-stock 5 --jq '.items[] | {name, changePercent}'
# {"name":"云天化","changePercent":"2.08%"}
# {"name":"东芯股份","changePercent":"-7.60%"}

bb-browser site info xueqiu/stock   # view adapter args, example, domain

Daemon configuration

The daemon binds to 127.0.0.1:19824 by default. You can customize the host with --host:

bb-browser daemon --host 127.0.0.1    # IPv4 only (fix macOS IPv6 issues)
bb-browser daemon --host 0.0.0.0      # listen on all interfaces (for Tailscale / ZeroTier remote access)

Architecture

AI Agent (Claude Code, Codex, Cursor, etc.)
       │ CLI or MCP (stdio)
       ▼
bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ Your Real Browser
                           │
                    ┌──────┴──────┐
                    │ Per-tab     │
                    │ event cache │
                    │ (network,   │
                    │  console,   │
                    │  errors)    │
                    └─────────────┘

License

MIT

bb-browser (epiral/bb-browser)

Searching Database…

6.2K ·GitHub
Bb-browser
这是什么？bb-browser 让 AI 智能体通过 CLI 或 MCP 服务器控制你本机真实的 Chrome 浏览器，借助你已有的登录会话，在 36 个平台（Twitter、Reddit、YouTube、GitHub、LinkedIn 等）上工作，无需 API 密钥，也无需抓取网页。
它是像 Playwright 那样的无头爬虫，还是别的东西？它是一个 CLI 工具加一个 MCP 服务器，直接操控你已登录的 Chrome 标签页，比如运行 eval、带上你的 Cookie 调用 fetch()，或调用页面自带的 webpack 模块，而不是启动一个隔离的无头浏览器。
我要怎么把它跑起来？按照 README 中“快速开始”的 Install 和 Use 步骤，将 CLI 连接到你的 Chrome 浏览器；它也可以作为 MCP 服务器配合 Claude Code 或 Cursor 使用。OpenClaw 用户则无需任何扩展，直接通过 OpenClaw 内置的浏览器即可使用。
试用之前我需要准备什么？只要 Node 就行吗，还是还需要别的？你需要 Node.js 18+，以及一个已登录你想使用的网站的真实 Chrome 浏览器；另外还需要一个运行在 127.0.0.1:19824 的本地守护进程，负责把你的 CLI 或智能体命令转发到该浏览器会话。
每个网站的支持效果都一样好吗？支持范围取决于社区编写的适配器（bb-sites）：像 Reddit 或 GitHub 这类基于简单 Cookie 的网站，添加大约只需一分钟；但像 Twitter 搜索、小红书这类需要 webpack 注入或 Pinia 存储访问的网站，则需要接近 10 分钟，而且网站一旦改版，更容易失效。
AI 智能体到底能看到我账号的哪些信息？由于命令是在你真实的浏览器标签页中执行的，智能体实际上会以你自己的登录状态和 Cookie 访问所有已连接的网站；唯一的中间环节是一个只监听你本机的守护进程。
开箱即用支持多少个网站和命令？支持 36 个平台和 103 个命令，涵盖搜索、社交、新闻、开发、视频、金融、招聘、知识、购物和工具等类别，包括 Twitter、GitHub、哔哩哔哩、知乎和维基百科。
我自己怎么添加新网站？让 AI 智能体“把 XX 网站做成 CLI”即可。它会阅读适配器指南，用 network --with-body 逆向分析 API，编写并测试适配器，然后提交 PR，通常可以完全自主完成。
我能只把它当作通用浏览器自动化工具用，而不仅仅给智能体用吗？可以。每个命令都支持 --json 输出、--jq 行内过滤，以及用 --tab 同时运行多个标签页，因此它也可以当作通用的 CLI 浏览器自动化工具使用。
为什么不直接用 Playwright 或 Selenium？这些工具运行的是隔离的、未登录的无头浏览器，网站很容易将其识别出来；bb-browser 则运行在你已登录的真实 Chrome 中，复杂的登录验证和反机器人检测会自动处理，因为操作的确实就是你本人。
What are similar projects?oc, Endoplexity, XActions, agent-browser, Agent-Reach, huashu-chrome, gemini-notebook-mcp-cli, playwright
Which topics is it in?chrome, chrome-extension, openclaw, web-scraping, browser-automation, model-context-protocol, cli-tool, cursor, browser, command-line, mcp-server, ai-agent
Creator
epiral
Size
0.6 MB
Stars
6.2K
Updated
CommitMay 29Releasebb-browser-v0.11.6May 11
Age
8mo
Commits · 90 Days