Skip to content
Back to search

bb-browser

Your browser is the API. CLI + MCP server for AI agents to control Chrome with your login state.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/epiral-bb-browser/badge.svg)](/listings/epiral-bb-browser)

HTML

<a href="/listings/epiral-bb-browser"><img src="/api/listings/epiral-bb-browser/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](https://openclaw.ai), 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](https://clawhub.ai/yan5xu/bb-browser)

MCP (Claude Code / Cursor)

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 194 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # bb-browser
  3. ### BadBoy Browser
  4. **Your browser is the API. No keys. No bots. No scrapers.**
  5. [![npm](https://img.shields.io/npm/v/bb-browser?color=CB3837&logo=npm&logoColor=white)](https://www.npmjs.com/package/bb-browser)
  6. [![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)](https://nodejs.org)
  7. [![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  8. [English](README.md) · [中文](README.zh-CN.md)
  9. </div>
  10. ---
  11. You're already logged into Twitter, Reddit, YouTube, Zhihu, Bilibili, LinkedIn, GitHub — bb-browser lets AI agents **use that directly**.
  12. ```bash
  13. bb-browser site twitter/search "AI agent" # search tweets
  14. bb-browser site zhihu/hot # trending on Zhihu
  15. bb-browser site arxiv/search "transformer" # search papers
  16. bb-browser site eastmoney/stock "茅台" # real-time stock quote
  17. bb-browser site boss/search "AI engineer" # search jobs
  18. bb-browser site wikipedia/summary "Python" # Wikipedia summary
  19. bb-browser site youtube/transcript VIDEO_ID # full transcript
  20. bb-browser site stackoverflow/search "async" # search SO questions
  21. ```
  22. **103 commands across 36 platforms.** All using your real browser's login state. [Full list →](https://github.com/epiral/bb-sites)
  23. ## The idea
  24. The internet was built for browsers. AI agents have been trying to access it through APIs — but 99% of websites don't offer one.
  25. 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.
  26. | | Playwright / Selenium | Scraping libs | bb-browser |
  27. |---|---|---|---|
  28. | Browser | Headless, isolated | No browser | Your real Chrome |
  29. | Login state | None, must re-login | Cookie extraction | Already there |
  30. | Anti-bot | Detected easily | Cat-and-mouse | Invisible — it IS the user |
  31. | Complex auth | Can't replicate | Reverse engineer | Page handles it itself |
  32. ## Quick Start
  33. ### Install
  34. ```bash
  35. npm install -g bb-browser
  36. ```
  37. ### Use
  38. ```bash
  39. bb-browser site update # pull community adapters
  40. bb-browser site recommend # see which adapters match your browsing habits
  41. bb-browser site zhihu/hot # go
  42. ```
  43. ### OpenClaw (no extension needed)
  44. If you use [OpenClaw](https://openclaw.ai), bb-browser runs directly through OpenClaw's built-in browser — no Chrome extension or daemon required:
  45. ```bash
  46. bb-browser site reddit/hot --openclaw
  47. bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[] | {name, changePercent}'
  48. ```
  49. Skill on ClawHub: [bb-browser-openclaw](https://clawhub.ai/yan5xu/bb-browser)
  50. ### MCP (Claude Code / Cursor)
  51. ```json
  52. {
  53. "mcpServers": {
  54. "bb-browser": {
  55. "command": "npx",
  56. "args": ["-y", "bb-browser", "--mcp"]
  57. }
  58. }
  59. }
  60. ```
  61. ## 36 platforms, 103 commands
  62. Community-driven via [bb-sites](https://github.com/epiral/bb-sites). One JS file per command.
  63. | Category | Platforms | Commands |
  64. |----------|-----------|----------|
  65. | **Search** | Google, Baidu, Bing, DuckDuckGo, Sogou WeChat | search |
  66. | **Social** | Twitter/X, Reddit, Weibo, Xiaohongshu, Jike, LinkedIn, Hupu | search, feed, thread, user, notifications, hot |
  67. | **News** | BBC, Reuters, 36kr, Toutiao, Eastmoney | headlines, search, newsflash, hot |
  68. | **Dev** | GitHub, StackOverflow, HackerNews, CSDN, cnblogs, V2EX, Dev.to, npm, PyPI, arXiv | search, issues, repo, top, thread, package |
  69. | **Video** | YouTube, Bilibili | search, video, transcript, popular, comments, feed |
  70. | **Entertainment** | Douban, IMDb, Genius, Qidian | movie, search, top250 |
  71. | **Finance** | Xueqiu, Eastmoney, Yahoo Finance | stock, hot stocks, feed, watchlist, search |
  72. | **Jobs** | BOSS Zhipin, LinkedIn | search, detail, profile |
  73. | **Knowledge** | Wikipedia, Zhihu, Open Library | search, summary, hot, question |
  74. | **Shopping** | SMZDM | search deals |
  75. | **Tools** | Youdao, GSMArena, Product Hunt, Ctrip | translate, phone specs, trending products |
  76. ## 10 minutes to add any website
  77. ```bash
  78. bb-browser guide # full tutorial
  79. ```
  80. 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.
  81. Three tiers of adapter complexity:
  82. | Tier | Auth method | Example | Time |
  83. |------|-------------|---------|------|
  84. | **1** | Cookie (fetch directly) | Reddit, GitHub, V2EX | ~1 min |
  85. | **2** | Bearer + CSRF token | Twitter, Zhihu | ~3 min |
  86. | **3** | Webpack injection / Pinia store | Twitter search, Xiaohongshu | ~10 min |
  87. 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.
  88. ## What this means for AI agents
  89. Without bb-browser, an AI agent's world is: **files + terminal + a few APIs with keys.**
  90. With bb-browser: **files + terminal + the entire internet.**
  91. An agent can now, in under a minute:
  92. ```bash
  93. # Cross-platform research on any topic
  94. bb-browser site arxiv/search "retrieval augmented generation"
  95. bb-browser site twitter/search "RAG"
  96. bb-browser site github search rag-framework
  97. bb-browser site stackoverflow/search "RAG implementation"
  98. bb-browser site zhihu/search "RAG"
  99. bb-browser site 36kr/newsflash
  100. ```
  101. Six platforms, six dimensions, structured JSON. Faster and broader than any human researcher.
  102. ## Also a full browser automation tool
  103. ```bash
  104. bb-browser open https://example.com
  105. bb-browser snapshot -i # accessibility tree
  106. bb-browser click @3 # click element
  107. bb-browser fill @5 "hello" # fill input
  108. bb-browser eval "document.title" # run JS
  109. bb-browser fetch URL --json # authenticated fetch
  110. bb-browser network requests --with-body --json # capture traffic
  111. bb-browser screenshot # take screenshot
  112. ```
  113. All commands support `--json` output, `--jq <expr>` for inline filtering, and `--tab <id>` for concurrent multi-tab operations.
  114. ```bash
  115. bb-browser site xueqiu/hot-stock 5 --jq '.items[] | {name, changePercent}'
  116. # {"name":"云天化","changePercent":"2.08%"}
  117. # {"name":"东芯股份","changePercent":"-7.60%"}
  118. bb-browser site info xueqiu/stock # view adapter args, example, domain
  119. ```
  120. ## Daemon configuration
  121. The daemon binds to `127.0.0.1:19824` by default. You can customize the host with `--host`:
  122. ```bash
  123. bb-browser daemon --host 127.0.0.1 # IPv4 only (fix macOS IPv6 issues)
  124. bb-browser daemon --host 0.0.0.0 # listen on all interfaces (for Tailscale / ZeroTier remote access)
  125. ```
  126. ## Architecture
  127. ```
  128. AI Agent (Claude Code, Codex, Cursor, etc.)
  129. │ CLI or MCP (stdio)
  130. ▼
  131. bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ Your Real Browser
  132. │
  133. ┌──────┴──────┐
  134. │ Per-tab │
  135. │ event cache │
  136. │ (network, │
  137. │ console, │
  138. │ errors) │
  139. └─────────────┘
  140. ```
  141. ## License
  142. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.