bb-browser

bb-browser - Information Retrieval & Browser Automation

Core Value

Through the browser + user login session, you can get:

• Public information: any public webpage, search results, news
• Private information: internal systems, enterprise apps, post-login pages, personal account data

Also perform browser operations on behalf of the user: form filling, button clicks, data extraction, screenshots, batch operations.

Runs in the user's real browser, reuses logged-in accounts, and avoids anti-scraping detection.

Quick Start

bb-browser open <url>        # Open page (new tab)
bb-browser snapshot -i       # Get interactive elements
bb-browser click @5          # Click element
bb-browser fill @3 "text"    # Fill input
bb-browser close             # Close tab when done

Site System — Turn Any Website into a CLI API

The site system is a core feature of bb-browser. It CLI-fies website functions via adapters, covering 36+ platforms.

# Common commands
bb-browser site list                          # List all adapters
bb-browser site search <query>                # Search adapters
bb-browser site <name> [args...]              # Run adapter
bb-browser site update                        # Update community adapter library

# Examples
bb-browser site twitter/search "Claude Code"  # Search tweets
bb-browser site zhihu/hot                     # Zhihu hot list
bb-browser site github/repo owner/repo        # Repo info
bb-browser site youtube/transcript <video_id> # Get transcript
bb-browser site reddit/thread <url>           # Post details
bb-browser site eastmoney/stock "茅台"         # Stock query
bb-browser site weibo/hot                     # Weibo hot search
bb-browser site arxiv/search "transformer"    # Paper search

Adapters automatically handle tab management (find matching domain tab or create new), and detect login errors with prompts.

Detailed usage and full list of 36 platforms: see references/site-system.md
Creating custom adapters: see references/adapter-development.md

fetch — curl with Login State

Execute fetch in the browser context, automatically carrying cookies and login state.

bb-browser fetch <url>                                    # GET request
bb-browser fetch <url> --method POST --body '{"k":"v"}'   # POST request
bb-browser fetch <url> --headers '{"Auth":"Bearer xxx"}'  # Custom headers
bb-browser fetch <url> --output data.json                 # Save to file
bb-browser fetch /api/me.json                             # Relative path (uses current tab origin)

Automatic domain routing: absolute URLs find matching tab or create new; relative paths use current tab.

Detailed usage: see references/fetch-and-network.md

Tab Management Rules

Must close tabs you opened after operations.

# Single tab scenario
bb-browser open https://example.com    # Open new tab
bb-browser snapshot -i
bb-browser click @5
bb-browser close                        # Close when done

# Multi-tab scenario
bb-browser open https://site-a.com     # tabId: 123
bb-browser open https://site-b.com     # tabId: 456
# ... operations ...
bb-browser tab close                    # Close current tab
bb-browser tab close                    # Close remaining tab

# Specify tab
bb-browser open https://example.com --tab current  # Open in current tab (no new tab)
bb-browser open https://example.com --tab 123      # Open in specified tabId

Core Workflow

1. open to load page
2. snapshot -i to view actionable elements (returns @ref)
3. Use @ref to perform actions (click, fill, etc.)
4. Re-snapshot -i after page changes
5. close tab when task is done

Command Reference

Navigation

bb-browser open <url>                # Open URL (new tab)
bb-browser open <url> --tab current  # Open in current tab
bb-browser back                      # Go back
bb-browser forward                   # Go forward
bb-browser refresh                   # Refresh
bb-browser close                     # Close current tab

Snapshot

bb-browser snapshot             # Full page structure
bb-browser snapshot -i          # Show only interactive elements (recommended)
bb-browser snapshot -c          # Remove empty structure nodes
bb-browser snapshot -d 3        # Limit tree depth to 3 levels
bb-browser snapshot -s ".main"  # Limit to CSS selector scope
bb-browser snapshot --json      # JSON output
# Options can be combined: bb-browser snapshot -i -c -d 5

Element Interaction

bb-browser click @5             # Click
bb-browser hover @5             # Hover
bb-browser fill @3 "text"       # Clear and fill
bb-browser type @3 "text"       # Append input (no clear)
bb-browser check @7             # Check checkbox
bb-browser uncheck @7           # Uncheck checkbox
bb-browser select @4 "option"   # Select dropdown
bb-browser press Enter          # Key press
bb-browser press Control+a      # Key combination
bb-browser scroll down          # Scroll down (default 300px)
bb-browser scroll up 500        # Scroll up 500px

Get Information

bb-browser get text @5          # Get element text
bb-browser get url              # Get current URL
bb-browser get title            # Get page title

Tab Management

bb-browser tab                  # List all tabs
bb-browser tab new [url]        # New tab
bb-browser tab 2                # Switch to 2nd tab (by index)
bb-browser tab select --id 123  # Switch to tab with specified tabId
bb-browser tab close            # Close current tab
bb-browser tab close 3          # Close 3rd tab (by index)
bb-browser tab close --id 123   # Close tab with specified tabId

Screenshot

bb-browser screenshot           # Screenshot (auto-save)
bb-browser screenshot path.png  # Screenshot to specified path

Wait

bb-browser wait 2000            # Wait 2 seconds
bb-browser wait @5              # Wait for element to appear

JavaScript

bb-browser eval "document.title"              # Execute JS
bb-browser eval "window.scrollTo(0, 1000)"    # Scroll to position

Frame Switching

bb-browser frame "#iframe-id"   # Switch to iframe
bb-browser frame main           # Return to main frame

Dialog Handling

bb-browser dialog accept        # Accept dialog
bb-browser dialog dismiss       # Dismiss dialog
bb-browser dialog accept "text" # Accept and input (prompt)

Network & Debugging

bb-browser network requests                        # View network requests
bb-browser network requests "api" --with-body       # Filter + full request/response body
bb-browser network route "*analytics*" --abort      # Intercept and block request
bb-browser network route "*/api/user" --body '{}'   # Intercept and mock response
bb-browser network unroute                          # Remove all intercept rules
bb-browser network clear                            # Clear request records
bb-browser console                                  # View console messages
bb-browser console --clear                          # Clear console
bb-browser errors                                   # View JS errors
bb-browser errors --clear                           # Clear error records
bb-browser trace start                              # Start recording user operations
bb-browser trace stop                               # Stop recording, output event list
bb-browser trace status                             # View recording status

Detailed network advanced usage: see references/fetch-and-network.md

Global Options

--json               # Output in JSON format (common to all commands)
--tab <tabId>        # Specify tab ID for operation (common to almost all commands)
--mcp                # Start MCP server (for AI tools like Claude Code / Cursor)

Ref Usage

The @ref returned by snapshot is a temporary identifier for elements:

@1 [button] "Submit"
@2 [input type="text"] placeholder="Enter name"
@3 [a] "View details"

Note:

• After page navigation, refs become invalid; re-snapshot
• After dynamic content loads, re-snapshot
• Ref format: @1, @2, @3...

Detailed explanation: see references/snapshot-refs.md

Concurrent Operations

# Open multiple pages concurrently (each in its own tab)
bb-browser open https://site-a.com &
bb-browser open https://site-b.com &
bb-browser open https://site-c.com &
wait
# Each returns an independent tabId, no interference

Information Extraction vs Page Operations

Choose different methods based on purpose:

Extract Page Content (use eval)

When extracting articles, body text, etc., use eval to get it directly:

# WeChat public account article
bb-browser eval "document.querySelector('#js_content').innerText"

# Zhihu answer
bb-browser eval "document.querySelector('.RichContent-inner').innerText"

# Generic: get page body text
bb-browser eval "document.body.innerText.substring(0, 5000)"

# Get all links
bb-browser eval "[...document.querySelectorAll('a')].map(a => a.href).join('\n')"

Some websites have deeply nested DOM; snapshot output is verbose. eval extracts text more efficiently.

Operate Page Elements (use snapshot -i)

When clicking, filling, selecting, use snapshot -i to get interactive elements:

bb-browser snapshot -i
# @1 [button] "Login"
# @2 [input] placeholder="Username"
# @3 [input type="password"]

bb-browser fill @2 "username"
bb-browser fill @3 "password"
bb-browser click @1

-i shows only interactive elements, filtering out irrelevant content.

MCP Integration

bb-browser provides an MCP server for integration with AI tools like Claude Code / Cursor:

# Start MCP server
bb-browser --mcp

Configuration example (Claude Code / Cursor):

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

Common Task Examples

Form Filling

bb-browser open https://example.com/form
bb-browser snapshot -i
bb-browser fill @1 "Zhang San"
bb-browser fill @2 "zhangsan@example.com"
bb-browser click @3
bb-browser wait 2000
bb-browser close

Information Extraction

bb-browser open https://example.com/dashboard
bb-browser snapshot -i
bb-browser get text @5
bb-browser screenshot report.png
bb-browser close

Batch Operations

for url in "url1" "url2" "url3"; do
  bb-browser open "$url"
  bb-browser snapshot -i --json
  bb-browser close
done

In-depth Documentation

Document	Description
references/site-system.md	Site system complete guide: 35 platform list, command usage, automatic tab management
references/adapter-development.md	Adapter development guide: API reverse engineering, three complexity levels, metadata format
references/fetch-and-network.md	Fetch & Network advanced features: requests with login state, request interception and mocking
references/snapshot-refs.md	Ref lifecycle, best practices, common issues