Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .github/ISSUE_TEMPLATE/bug_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@ Describe the problem in one or two sentences.
bb-browser ...
```

If relevant, include the exact command you ran and whether you used `--json`, `--openclaw`, or `--mcp`.
If relevant, include the exact command you ran and whether you used `--json` or `--openclaw`.

如果相关,请贴出你实际运行的完整命令,并说明是否使用了 `--json`、`--openclaw` 或 `--mcp`。
如果相关,请贴出你实际运行的完整命令,并说明是否使用了 `--json` 或 `--openclaw`。

## Steps To Reproduce / 复现步骤

Expand All @@ -42,11 +42,11 @@ What actually happened?
## Environment / 环境信息

- `bb-browser` version:
- Install method (`npm -g`, `npx`, local build, MCP, other):
- Install method (`npm -g`, `npx`, local build, other):
- OS:
- Node.js version:
- Browser:
- Extension installed? (`yes` / `no`)
- Chrome CDP source (`managed Chrome`, external `BB_BROWSER_CDP_URL`, other):
- OpenClaw used? (`yes` / `no`)

## Logs Or Output / 日志与输出
Expand Down
3 changes: 1 addition & 2 deletions .github/ISSUE_TEMPLATE/feature_request.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,12 +38,11 @@ Explain the user value, workflow gap, or agent use case.
Check anything relevant:

- [ ] CLI command
- [ ] Extension behavior
- [ ] Daemon behavior
- [ ] `site` adapter
- [ ] OpenClaw integration
- [ ] Hub / remote agent workflow
- [ ] JSON output
- [ ] MCP / agent workflow

## Alternatives Considered / 备选方案

Expand Down
20 changes: 10 additions & 10 deletions PRIVACY.md
Original file line number Diff line number Diff line change
@@ -1,29 +1,29 @@
# Privacy Policy — bb-browser

**Last updated:** 2026-03-14
**Last updated:** 2026-06-01

## What bb-browser does

bb-browser is a browser automation tool that lets AI agents control your Chrome browser via the Chrome DevTools Protocol (CDP). It consists of a CLI, an MCP server, a local HTTP daemon, and a Chrome extension.
bb-browser is a browser automation tool that lets AI agents control your Chrome browser via the Chrome DevTools Protocol (CDP). It consists of a CLI and a local HTTP daemon. In Hub mode, the daemon can also register with Pinix Hub so remote clients can invoke the same commands.

## Data handling

All communication happens **locally on your machine**:

```
AI Agent ↔ CLI/MCP ↔ localhost:19824 (daemon) ↔ Chrome Extension
AI Agent ↔ CLI ↔ localhost:19824 (daemon) ↔ Chrome CDP
```

**No data is sent to any external server.** There is no telemetry, no analytics, no cloud service.
In local CLI mode, no browser data is sent to any external server. There is no telemetry or analytics. In Hub mode, command requests and responses flow through the configured Hub endpoint because that mode is explicitly remote.

## What data is accessed

When you use bb-browser, the extension may access the following data **locally**:
When you use bb-browser, the daemon may access the following data:

| Data type | How it's used | Stored? |
|-----------|---------------|---------|
| **Tab URLs and titles** | To list and route commands to the correct tab | In memory only, cleared on extension restart |
| **Page content** | Snapshot (accessibility tree) and eval commands read page DOM | Not stored, returned to local CLI/MCP only |
| **Tab URLs and titles** | To list and route commands to the correct tab | In memory only, cleared on daemon restart |
| **Page content** | Snapshot (accessibility tree) and eval commands read page DOM | Not stored, returned to the CLI or Hub caller |
| **Authentication state** | Fetch commands use the browser's existing cookies/sessions | Not accessed directly, browser handles this natively |
| **User activity** | Trace feature records clicks, keystrokes, and scrolling for replay | In memory only, cleared on stop |
| **Network requests** | Network monitoring captures request/response data | In memory only, bounded buffer, cleared on tab close |
Expand All @@ -32,17 +32,17 @@ When you use bb-browser, the extension may access the following data **locally**

- No personally identifiable information
- No browsing history is recorded or persisted
- No data is transmitted to external servers
- No data is transmitted to external servers in local CLI mode
- No analytics or telemetry
- No cookies or credentials are extracted or stored

## Data retention

All data exists only in memory during the browser session. No data is written to disk by the extension. When the extension is unloaded or the browser is closed, all data is gone.
Browser data exists only in memory during the daemon session. When the daemon or browser is closed, in-memory tab state and event buffers are gone.

## Third parties

bb-browser does not share any data with third parties. The extension communicates exclusively with a daemon process running on localhost.
In local CLI mode, bb-browser does not share data with third parties. In Hub mode, the daemon communicates with the Hub endpoint you configured.

## Open source

Expand Down
22 changes: 6 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,9 @@ bb-browser site recommend # see which adapters match your browsing habits
bb-browser site zhihu/hot # go
```

### OpenClaw (no extension needed)
### OpenClaw (no daemon needed)

If you use [OpenClaw](https://openclaw.ai), bb-browser runs directly through OpenClaw's built-in browser — no Chrome extension or daemon required:
If you use [OpenClaw](https://openclaw.ai), bb-browser runs directly through OpenClaw's built-in browser — no local daemon required:

```bash
bb-browser site reddit/hot --openclaw
Expand All @@ -71,19 +71,6 @@ bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[] | {name, changePerc

Skill on ClawHub: [bb-browser-openclaw](https://clawhub.ai/yan5xu/bb-browser)

### MCP (Claude Code / Cursor)

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

## 36 platforms, 103 commands

Community-driven via [bb-sites](https://github.com/epiral/bb-sites). One JS file per command.
Expand Down Expand Up @@ -176,7 +163,7 @@ bb-browser daemon --host 0.0.0.0 # listen on all interfaces (for Tailscale

```
AI Agent (Claude Code, Codex, Cursor, etc.)
│ CLI or MCP (stdio)
│ CLI
▼
bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ Your Real Browser
│
Expand All @@ -187,6 +174,9 @@ bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ Your Real
│ console, │
│ errors) │
└─────────────┘

Optional Hub mode registers the daemon with Pinix Hub so remote clients can
invoke the same browser commands through the daemon.
```

## License
Expand Down
18 changes: 4 additions & 14 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,19 +71,6 @@ bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[] | {name, changePerc

ClawHub Skill: [bb-browser-openclaw](https://clawhub.ai/yan5xu/bb-browser)

### MCP 接入(Claude Code / Cursor)

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

## 36 个平台,103 个命令

社区驱动,通过 [bb-sites](https://github.com/epiral/bb-sites) 维护。每个命令一个 JS 文件。
Expand Down Expand Up @@ -176,7 +163,7 @@ bb-browser daemon --host 0.0.0.0 # 监听所有网卡(用于 Tailscale /

```
AI Agent (Claude Code, Codex, Cursor 等)
│ CLI 或 MCP (stdio)
│ CLI
▼
bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ 你的真实浏览器
│
Expand All @@ -187,6 +174,9 @@ bb-browser CLI ──HTTP──▶ Daemon ──CDP WebSocket──▶ 你的真
│ console, │
│ errors) │
└─────────────┘

可选 Hub 模式会把 daemon 注册到 Pinix Hub,远程客户端也可以通过 daemon
调用同一套浏览器命令。
```

## 许可证
Expand Down
1 change: 0 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,6 @@
"ai",
"agent",
"chrome",
"extension",
"cli",
"puppeteer",
"playwright",
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/src/commands/open.ts
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ export async function openCommand(
(request as Record<string, unknown>).tabId = tabId;
}
}
// 不指定 --tab 时,tabId 为 undefined,扩展会创建新 tab
// 不指定 --tab 时,tabId 为 undefined,daemon 会创建新 tab

// 发送请求
const response: Response = await sendCommand(request);
Expand Down
27 changes: 0 additions & 27 deletions packages/daemon/src/cdp-connection.ts
Original file line number Diff line number Diff line change
Expand Up @@ -30,33 +30,6 @@ export interface CdpTargetInfo {
url: string;
}

// ---------------------------------------------------------------------------
// Stealth — hide headless/automation fingerprints
// ---------------------------------------------------------------------------

const STEALTH_USER_AGENT =
"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/149.0.7827.22 Safari/537.36";

const STEALTH_UA_METADATA = {
brands: [
{ brand: "Chromium", version: "149" },
{ brand: "Google Chrome", version: "149" },
{ brand: "Not.A/Brand", version: "24" },
],
fullVersionList: [
{ brand: "Chromium", version: "149.0.7827.22" },
{ brand: "Google Chrome", version: "149.0.7827.22" },
{ brand: "Not.A/Brand", version: "24.0.0.0" },
],
platform: "macOS",
platformVersion: "10.15.7",
architecture: "x86",
bitness: "64",
model: "",
mobile: false,
wow64: false,
};

const STEALTH_SCRIPT = `
(() => {
if (window.__bbStealthApplied) return;
Expand Down
2 changes: 0 additions & 2 deletions packages/daemon/src/chrome.ts
Original file line number Diff line number Diff line change
Expand Up @@ -178,13 +178,11 @@ async function downloadAndExtractChrome(platform: Platform): Promise<string> {
// Try download sources in order
const urls = getDownloadUrls(platform);
let resp: Response | null = null;
let usedUrl = "";

for (const url of urls) {
console.error(`${LOG_PREFIX} Downloading Chrome ${CHROME_VERSION} (${platform}) from ${new URL(url).host}...`);
resp = await tryFetch(url);
if (resp) {
usedUrl = url;
break;
}
console.error(`${LOG_PREFIX} Download failed, trying next source...`);
Expand Down
3 changes: 1 addition & 2 deletions packages/daemon/src/command-dispatch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,8 @@ import type {
TraceEntry,
TraceStatus,
} from "@bb-browser/shared";
import { CdpConnection, type CdpTargetInfo } from "./cdp-connection.js";
import { CdpConnection } from "./cdp-connection.js";
import type { TabState } from "./tab-state.js";
import type { ActionDetail } from "./tab-state.js";
import { getAllSites, executeSiteAdapter } from "./site-adapter.js";

// ---------------------------------------------------------------------------
Expand Down
21 changes: 14 additions & 7 deletions packages/daemon/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -330,10 +330,17 @@ async function main(): Promise<void> {
// Clean up any stale daemon before starting
await cleanupStaleDaemon();

// Auto-manage Chrome headless-shell (unless --no-chrome)
// Prefer an already-available CDP endpoint (explicit port or managed port
// file). Only launch Chrome if nothing is reachable.
let chromeProcess: ChildProcess | null = null;
let cdpEndpoint: { host: string; port: number } | null = null;

try {
cdpEndpoint = await discoverCdpPort(options.cdpHost, options.cdpPort);
} catch {}

if (!options.noChrome) {
// Auto-manage Chrome headless-shell (unless --no-chrome)
if (!cdpEndpoint && !options.noChrome) {
const chrome = createChromeManager();

// Ensure headless-shell binary is available (download if needed)
Expand Down Expand Up @@ -361,23 +368,23 @@ async function main(): Promise<void> {
try {
chromeProcess = chrome.launch(options.cdpPort);
await chrome.waitForCdp(options.cdpHost, options.cdpPort);
cdpEndpoint = { host: options.cdpHost, port: options.cdpPort };
} catch (error) {
console.error(`[Daemon] Failed to launch Chrome: ${error instanceof Error ? error.message : String(error)}`);
}
} else {
console.error(`[Daemon] Chrome already running on port ${options.cdpPort}`);
cdpEndpoint = { host: options.cdpHost, port: options.cdpPort };
}
}

// Create tab state manager and CDP connection
const tabManager = new TabStateManager();
let cdpEndpoint: { host: string; port: number };

try {
cdpEndpoint = await discoverCdpPort(options.cdpHost, options.cdpPort);
} catch (error) {
if (!cdpEndpoint) {
console.error(
`[Daemon] ${error instanceof Error ? error.message : String(error)}`,
`[Daemon] Cannot connect to Chrome CDP at ${options.cdpHost}:${options.cdpPort}. ` +
`Make sure Chrome is running with --remote-debugging-port=${options.cdpPort}`,
);
process.exit(1);
}
Expand Down
3 changes: 1 addition & 2 deletions packages/shared/src/protocol.ts
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ export interface TabInfo {
title: string;
/** 是否是当前活动标签页 */
active: boolean;
/** 标签页 ID(CDP targetId 或 extension tabId) */
/** 标签页 ID(CDP targetId 或 daemon short ID) */
tabId: number | string;
/** 短标签页 ID(daemon 模式) */
tab?: string;
Expand Down Expand Up @@ -397,4 +397,3 @@ export interface DaemonStatus {
}>;
}


22 changes: 0 additions & 22 deletions skills/bb-browser/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,6 @@ bb-browser trace status # 查看录制状态
```bash
--json # 以 JSON 格式输出(所有命令通用)
--tab <tabId> # 指定操作的标签页 ID(几乎所有命令通用)
--mcp # 启动 MCP server(用于 Claude Code / Cursor 等 AI 工具)
```

## Ref 使用说明
Expand Down Expand Up @@ -294,27 +293,6 @@ bb-browser click @1

`-i` 只显示可交互元素,过滤掉大量无关内容。

## MCP 集成

bb-browser 提供 MCP server,可与 Claude Code / Cursor 等 AI 工具集成:

```bash
# 启动 MCP server
bb-browser --mcp
```

配置示例(Claude Code / Cursor):
```json
{
"mcpServers": {
"bb-browser": {
"command": "npx",
"args": ["-y", "bb-browser", "--mcp"]
}
}
}
```

## 常见任务示例

### 表单填写
Expand Down
Loading