bb-browser

Overview

Use this skill when the user wants to use the web through their real browser session inside NextClaw.

This marketplace skill wraps the upstream epiral/bb-browser project for NextClaw users.

Be explicit about the boundary:

• This skill owns explanation, installation guidance, readiness checks, workflow selection, and risk disclosure.
• The local bb-browser CLI owns actual browser execution.
• The user's browser login state owns access to private pages and authenticated requests.

Do not pretend the environment is ready when it is not.

What This Skill Covers

• site adapters such as twitter/search, reddit/thread, github/repo, zhihu/hot, youtube/transcript,
• authenticated browser-backed fetch,
• browser automation flows such as open, snapshot, click, fill, eval, network requests, and screenshot,
• local daemon mode with the user's real Chrome state,
• optional --openclaw path when the user already wants to run through OpenClaw's browser,
• first-use setup and bounded troubleshooting.

What This Skill Does Not Cover

• inventing site adapters or flags that bb-browser does not expose,
• pretending a site command is safe when it can write, post, delete, purchase, or change account state,
• hiding missing prerequisites such as the local CLI, running browser, daemon connectivity, or login state,
• presenting third-party browser execution as native built-in NextClaw capability,
• silently creating or publishing new adapters to the upstream ecosystem.

Install Boundary

Always distinguish these paths:

• NextClaw marketplace skill install: nextclaw skills install bb-browser
• Upstream runtime install: npm install -g bb-browser
• Optional MCP wiring outside NextClaw: configure bb-browser --mcp in the target MCP client

Installing the marketplace skill does not install the upstream runtime automatically.

Deterministic First-Use Workflow

When the user asks for a bb-browser task, follow this order.

1. Classify the task

Choose exactly one:

• site read,
• browser read,
• browser write or account-affecting action,
• adapter authoring or reverse-engineering help.

Prefer the smallest workflow that fits the request.

2. Verify the CLI exists

Run:

command -v bb-browser
bb-browser --version

If missing, explain that the local runtime is not installed yet.

Recommended install:

npm install -g bb-browser

Do not continue to the real task until bb-browser exists.

3. Choose the execution path

Use exactly one of these:

• Default daemon path Use the user's local Chrome session.
• OpenClaw path Only when the user explicitly wants OpenClaw or already has that browser path ready. Every site command must include --openclaw.

Do not mix the two paths in one command.

4. Run a readiness check

For the default daemon path, ask the user to keep Chrome running, then run:

bb-browser status --json

If it reports running: false or no daemon state, try:

bb-browser daemon

Then re-run:

bb-browser status --json

Success means the daemon is running and Chrome is connected.

For the OpenClaw path, first verify bb-browser exists, then use a lightweight read such as:

bb-browser site list --openclaw

If that works, proceed with the real site task.

5. Run one read-only smoke before risky work

Prefer a read-only command first.

Examples:

bb-browser site list
bb-browser site info reddit/thread
bb-browser site recommend
bb-browser get title
bb-browser eval "document.title"

If adapter coverage is the goal, refresh the community adapter list first:

bb-browser site update

Do not jump straight into write actions if a small read can verify readiness first.

6. Execute the smallest matching command

Examples:

bb-browser site reddit/hot
bb-browser site github/repo owner/repo
bb-browser site youtube/transcript VIDEO_ID
bb-browser fetch https://example.com/api/me --json
bb-browser open https://example.com
bb-browser snapshot -i
bb-browser click @3
bb-browser fill @5 "hello"
bb-browser network requests --with-body

If using OpenClaw for site commands:

bb-browser site reddit/hot --openclaw
bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[] | {name, changePercent}'

Safe Execution Rules

• Prefer site adapters over manual browser clicking when both can solve the task clearly.
• Prefer read-only commands before writes.
• Treat posting, deleting, following, liking, submitting forms, changing settings, purchases, and account mutations as write actions that need explicit confirmation unless the user already gave a clear scoped instruction.
• If the request only needs information extraction, prefer site, fetch, get, or eval before click or fill.
• If using snapshot refs, remember that refs are temporary and must be refreshed after navigation or page changes.
• Close tabs that you opened for the task when they are no longer needed.

Troubleshooting

bb-browser not found

• Explain that the upstream CLI is not installed locally.
• Guide installation with npm install -g bb-browser.
• Re-check with command -v bb-browser.

Daemon not running or Chrome not connected

• Ask the user to keep Chrome open.
• Run bb-browser status --json.
• If needed, start the daemon with bb-browser daemon and check status again.
• If startup still fails, be explicit that the local browser bridge is not ready yet.

Site command fails or returns unauthorized data

• Explain that the most likely cause is missing or expired login state in the browser.
• Ask the user to log into the target site in Chrome or OpenClaw browser, then retry.

Adapter missing or outdated

• Use:

bb-browser site list
bb-browser site search <keyword>
bb-browser site info <name>
bb-browser site update

• Do not claim support for an adapter you have not confirmed.

Ref stopped working

• Explain that @ref values expire after navigation or DOM changes.
• Re-run:

bb-browser snapshot -i

The user wants a brand new website adapter

• Be explicit that this is upstream adapter-authoring work, not guaranteed built-in support.
• Use bb-browser guide to inspect the upstream guide before proposing implementation steps.
• Do not claim the adapter already exists unless site list or site search proves it.

Success Criteria

This skill is working correctly when:

• the user understands that execution is performed by the local bb-browser runtime,
• missing CLI, daemon, browser, or login prerequisites are identified before task execution,
• a read-only smoke succeeds before heavier workflows when appropriate,
• write actions stay behind explicit confirmation when required,
• and the final task runs only after the environment is truly ready.

Attribution

This skill adapts the upstream epiral/bb-browser project for the NextClaw marketplace.