bb-browser - Information Retrieval and Browser Automation

Core Value

bb-browser is a powerful information retrieval tool.

With browsers + user login states, you can obtain:

Public domain information: Any public web pages, search results, news and information
Private domain information: Internal systems, enterprise applications, post-login pages, personal account data

On this basis, it can also perform browser operations on behalf of users:

Form filling, button clicking
Data extraction, screenshot saving
Batch operations, repetitive tasks

Why can it do this?

Runs in the user's real browser, reusing logged-in accounts
Does not trigger anti-crawling detection, accessing protected pages
No need to provide passwords or Cookies, directly using existing login states

Quick Start

bash

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 box
bb-browser close             # Close tab after completion

Tab Management Specifications

Important: You must close the tabs you opened after completing operations

bash

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

# Multiple tabs 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

# Specified tab operations
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

```
open
```
Open the page
```
snapshot -i
```
View operable elements (returns @ref)
Use
```
@ref
```
to perform operations (click, fill, etc.)
Re-run
```
snapshot -i
```
after page changes
```
close
```
the tab after task completion

Command Quick Reference

Navigation

bash

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

bash

bb-browser snapshot             # Complete page structure
bb-browser snapshot -i          # Only display interactive elements (recommended)
bb-browser snapshot --json      # Output in JSON format

Element Interaction

bash

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"   # Dropdown selection
bb-browser press Enter          # Press key
bb-browser press Control+a      # Press key combination
bb-browser scroll down          # Scroll down
bb-browser scroll up 500        # Scroll up 500px

Information Retrieval

bash

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

Tab Management

bash

bb-browser tab                  # List all tabs
bb-browser tab new [url]        # Create new tab
bb-browser tab 2                # Switch to 2nd tab
bb-browser tab close            # Close current tab
bb-browser tab close 3          # Close 3rd tab

Screenshot

bash

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

Wait

bash

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

JavaScript

bash

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

Frame Switching

bash

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

Dialog Handling

bash

bb-browser dialog accept        # Confirm dialog
bb-browser dialog dismiss       # Cancel dialog
bb-browser dialog accept "text" # Confirm and input (prompt)

Debugging

bash

bb-browser network requests     # View network requests
bb-browser console              # View console messages
bb-browser errors               # View JS errors
bb-browser trace start          # Start recording user operations
bb-browser trace stop           # Stop recording

Ref Usage Instructions

The

@ref

returned by snapshot is a temporary identifier for elements:

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

Notes:

Ref becomes invalid after page navigation, need to re-run snapshot
Need to re-run snapshot after dynamic content loads
Ref format:
```
@1
```
,
```
@2
```
,
```
@3
```
...

Concurrent Operations

bash

# Open multiple pages concurrently (each in independent 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 independent tabId, no interference

JSON Output

Add

--json

to get structured output:

bash

bb-browser snapshot -i --json
bb-browser get text @5 --json
bb-browser open https://example.com --json

Information Retrieval vs Page Operations

Choose different methods based on your purpose:

Extract Page Content (use eval)

When you need to extract long text such as articles or main content, use

eval

to get it directly:

bash

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

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

# General: Get page main 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')"

Why not use snapshot? Some websites (such as WeChat Official Accounts) have deeply nested DOM structures, so snapshot output will be very lengthy.

eval

directly extracts text more efficiently.

Operate Page Elements (use snapshot -i)

When you need to click, fill, or select, use

snapshot -i

to get interactive elements:

bash

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
is important: Only displays interactive elements, filtering out a large amount of irrelevant content.

Common Task Examples

Form Filling

bash

bb-browser open https://example.com/form
bb-browser snapshot -i
# @1 [input] placeholder="Name"
# @2 [input] placeholder="Email"
# @3 [button] "Submit"

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 Retrieval

bash

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

Batch Operations

bash

# Open multiple pages to extract information
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/snapshot-refs.md	Ref lifecycle, best practices, common issues

bb-browser

NPX Install

Tags

SKILL.md Content (Chinese)

bb-browser - Information Retrieval and Browser Automation

Core Value

Quick Start

Tab Management Specifications

Core Workflow

Command Quick Reference

Navigation

Snapshot

Element Interaction

Information Retrieval

Tab Management

Screenshot

Wait

JavaScript

Frame Switching

Dialog Handling

Debugging

Ref Usage Instructions

Concurrent Operations

JSON Output

Information Retrieval vs Page Operations

Extract Page Content (use eval)

Operate Page Elements (use snapshot -i)

Common Task Examples

Form Filling

Information Retrieval

Batch Operations

In-Depth Documentation