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
What is this?bb-browser lets AI agents control your real Chrome browser via a CLI or MCP server, using your existing login sessions to work with 36 platforms (Twitter, Reddit, YouTube, GitHub, LinkedIn, etc.) without API keys or scraping.
Is this a headless scraper like Playwright, or something else?It is a CLI tool plus an MCP server that drives your actual logged-in Chrome tab — running eval, calling fetch() with your cookies, or invoking the page's own webpack modules — instead of spinning up an isolated headless browser.
How do I get it running?Follow the Quick Start Install/Use steps in the README to connect the CLI to your Chrome browser; it also runs as an MCP server for Claude Code or Cursor, and OpenClaw users can use it directly through OpenClaw's built-in browser with no extension at all.
What do I need before trying it — just Node, or anything else?You need Node.js 18+ and a real Chrome browser already logged into whatever sites you want to use; a local daemon on 127.0.0.1:19824 bridges your CLI/agent commands to that browser session.
Does every website work equally well?Coverage depends on community-written adapters (bb-sites): simple cookie-based sites like Reddit or GitHub take about a minute to add, but sites needing webpack injection or Pinia-store access (e.g. Twitter search, Xiaohongshu) take closer to 10 minutes and are more likely to break if the site changes.
What does the AI agent actually see of my accounts?Because commands execute inside your real browser tab, the agent effectively acts with your own login state and cookies for every connected site, mediated only by a daemon that listens on your local machine.
How many sites and commands does it support out of the box?36 platforms and 103 commands spanning search, social, news, dev, video, finance, jobs, knowledge, shopping and tools — including Twitter, GitHub, Bilibili, Zhihu and Wikipedia.
How do I add a new website myself?Tell an AI agent to 'turn XX website into a CLI' — it reads the adapter guide, reverse-engineers the API with network --with-body, writes and tests the adapter, then submits a PR, often fully autonomously.
Can I use it as a plain browser automation tool, not just for agents?Yes — every command supports --json output, --jq inline filtering, and --tab for running multiple tabs concurrently, so it doubles as a general CLI browser-automation tool.
Why not just use Playwright or Selenium?Those tools run isolated, logged-out headless browsers that sites can detect; bb-browser runs inside your already-logged-in real Chrome, so complex auth and anti-bot checks are handled automatically because it genuinely is you.
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