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:

1. chrome://extensions/ → Enable Developer Mode
2. "Load unpacked" → select node_modules/bb-browser/extension/
3. 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