Package Exports

bb-browser
bb-browser/dist/cli.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (bb-browser) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

bb-browser

BadBoy Browser

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

English · 中文

You're already logged into Gmail, Twitter, Reddit, Xiaohongshu — bb-browser lets AI agents use that. Not by stealing cookies or faking fingerprints. By being the browser.

AI Agent (Claude Code, Codex, etc.)
       │ CLI commands
       ▼
bb-browser CLI ──HTTP──▶ Daemon ──SSE──▶ Chrome Extension
                                              │
                                              ▼ chrome.debugger (CDP)
                                         Your Real Browser
                                    (logged-in sites, cookies, sessions)

Why

Every scraping tool tries to pretend it's a browser. bb-browser is the browser.

	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 game	Invisible — it IS the user
Internal sites	Need VPN/proxy setup	Can't reach	If you can see it, so can the agent

What it can do

Browser Automation

bb-browser open https://example.com
bb-browser snapshot -i           # interactive elements only
bb-browser click @0              # click by ref
bb-browser fill @2 "hello"       # fill input
bb-browser press Enter
bb-browser screenshot

Authenticated Fetch

Like curl, but with your browser's login state. No API keys, no tokens.

# Reddit — you're logged in, just fetch
bb-browser fetch https://www.reddit.com/api/me.json

# Any website's internal API — the browser handles auth
bb-browser fetch https://api.example.com/user/profile --json

Network Capture

See what any website sends and receives — request headers, bodies, response data. Like Chrome DevTools Network tab, but from CLI.

bb-browser network requests --filter "api.example.com" --with-body --json
# → Full request headers (including auth/signing), full response body
# → See exactly how a website's API works — then build an adapter for it

Site Adapters

Pre-built commands for popular websites. Community-driven via bb-sites.

bb-browser site update                                    # install adapters
bb-browser site reddit/thread https://reddit.com/r/...    # Reddit discussion tree
bb-browser site twitter/user yan5xu                        # Twitter profile
bb-browser site xiaohongshu/feed                           # Xiaohongshu feed
bb-browser site hackernews/top                             # HN front page

Xiaohongshu has request signing (X-s headers). Our adapters call the page's own Vue/Pinia store actions — the page signs the requests itself. Zero reverse engineering needed.

Install

npm install -g bb-browser

Then load the Chrome extension:

chrome://extensions/ → Enable Developer Mode
"Load unpacked" → select node_modules/bb-browser/extension/
Done.

bb-browser daemon    # start the daemon
bb-browser status    # verify connection

Command Reference

Category	Command	Description
Navigate	`open <url>`	Open URL
	`back` / `forward` / `refresh`	Navigate
	`close`	Close tab
Snapshot	`snapshot`	Full DOM tree
	`snapshot -i`	Interactive elements only
Interact	`click <ref>`	Click element
	`fill <ref> <text>`	Clear and fill
	`type <ref> <text>`	Append text
	`hover <ref>`	Hover
	`press <key>`	Keyboard (Enter, Tab, Control+a)
	`scroll <dir> [px]`	Scroll
	`check` / `uncheck <ref>`	Checkbox
	`select <ref> <val>`	Dropdown
Data	`get text <ref>`	Element text
	`get url` / `get title`	Page info
	`screenshot [path]`	Screenshot
	`eval "<js>"`	Run JavaScript
Fetch	`fetch <url> [--json]`	Authenticated HTTP fetch
Site	`site list`	List site adapters
	`site <name> [args]`	Run adapter
	`site update`	Update community adapters
Network	`network requests [filter]`	View requests
	`network requests --with-body`	Include headers & body
	`network route "<url>" --abort`	Block requests
	`network clear`	Clear records
Tab	`tab`	List tabs
	`tab new [url]`	New tab
	`tab <n>`	Switch tab
Debug	`console` / `errors`	Console & JS errors
	`trace start` / `trace stop`	Record user actions
Daemon	`daemon` / `stop` / `status`	Manage daemon

All commands support --json for structured output and --tab <id> for multi-tab operations.

Architecture

bb-browser/
├── packages/
│   ├── cli/          # CLI (TypeScript, argument parsing, HTTP client)
│   ├── daemon/       # HTTP daemon (SSE bridge, request-response matching)
│   ├── extension/    # Chrome extension (Manifest V3, chrome.debugger CDP)
│   └── shared/       # Shared types and protocol definitions
├── dist/             # Build output (npm publish)
└── extension/        # Built extension (npm publish)

Layer	Tech
CLI	TypeScript, zero dependencies
Daemon	Node.js HTTP + SSE
Extension	Chrome MV3 + `chrome.debugger` API
Build	pnpm monorepo + Turborepo + tsup + Vite

License

MIT