/browser-control

name: browser-control
description: Use the local browser-connector CLI to inspect and operate the user's current Chrome tabs through the Browser Connector extension and Native Host. Use when the user asks to list open browser pages, read a current page, capture a screenshot, or perform controlled browser interactions from NextClaw.

Browser Control

Use this skill when the user wants the AI to inspect or operate Chrome pages that are already open in the user's normal browser.

This is a wrapped external tool skill:

• The skill owns setup guidance, readiness checks, safe workflow order, confirmation rules, and troubleshooting.
• `browser-connector` owns the Chrome Extension, Native Messaging Host, tab lease, JSON contract, screenshots, DOM snapshots, and browser actions.
• Do not present this as a built-in NextClaw browser runtime or as direct model vision.

What This Skill Covers

• List currently open Chrome tabs.
• Open a new Chrome tab for an http or https URL.
• Keep new tabs in the background by default for temporary evaluation, research, and page-reading work.
• Ask the connected unpacked Browser Connector extension to reload itself after local or package updates.
• Read the selected tab or refresh metadata for a known tab.
• Claim a tab before reading or operating it.
• Read a bounded page snapshot.
• Locate ref-addressable interactive elements by text, label, placeholder, role, or kind.
• Capture a visible-tab screenshot, optionally writing it to a local PNG file.
• Navigate a claimed tab with goto, reload, back, and forward.
• Inspect elements, fill editable fields with verified state, click, type, press

keys, scroll, wait, and read captured page logs through the connector.

• Release the tab lease when done.

What This Skill Does Not Cover

• Reading cookies, localStorage, sessionStorage, passwords, browser history, or extension private storage.
• Bypassing website authentication or permission prompts.
• Automatically confirming submit, send, upload, delete, payment, login, or permission actions.
• Long-running daemon management.
• Operating a separate Playwright browser instead of the user's current Chrome.

Readiness Check

First check whether `browser-connector` is available:

command -v browser-connector
browser-connector --version

If it is not installed, install the published package:

npm install -g @nextclaw/browser-connector

If global install is not appropriate, use `npx` for one-off diagnostics:

npx -y @nextclaw/browser-connector@latest --version

Prefer a stable installed binary for multi-step browser workflows because tab leases and Native Host IPC depend on consistent local state.

First-Use Setup

Use the one-step setup command first. If the current workspace is the NextClaw source repo and contains `packages/browser-connector/package.json`, prefer the local source setup script:

pnpm browser-connector:setup:open

Otherwise use the installed CLI:

browser-connector setup chrome --open --json

If `ready` is true, proceed to the workflow.

If `ready` is false, follow only the returned `nextSteps`. Usually the command already opened `chrome://extensions` and the extension directory; the user only needs to load the returned `nativeHost.extensionDir` as an unpacked extension. Then rerun the same setup command.

If `chrome-extension-capabilities` is false while `chrome-extension` is true, the CLI and Native Host are connected but Chrome is still running an older unpacked extension background script. Prefer:

browser-connector extension reload --reason "refresh extension capabilities after CLI update" --json
browser-connector setup chrome --json

If `extension reload` itself returns `UNSUPPORTED_COMMAND`, the currently loaded extension is too old to self-reload. Reload it once in `chrome://extensions`, then rerun setup. Do not continue with newer commands until this check is true.

For local NextClaw source testing, rerun:

pnpm browser-connector:setup

For installed CLI testing, rerun:

browser-connector setup chrome --json

Use `doctor` only for troubleshooting or when setup did not become ready:

browser-connector doctor --json

Do not ask the user to manually run the full lower-level command chain unless debugging setup failure.

Workflow

Always follow this order:

1. Open a new tab only when the user asks to visit a URL or the task requires a fresh page:

browser-connector tabs open "https://example.com/" --reason "<why opening>" --json
browser-connector tabs open "https://example.com/" --reason "<why opening>" --foreground --json

`tabs open` keeps the new tab in the background by default so AI evaluation does not interrupt the user's active Chrome tab. Use `--foreground` only when the user explicitly asks to open and view the page now, or when the next action truly needs the new page to become active. `--background` is accepted as an explicit no-focus signal, but it is no longer required.

2. List tabs:

browser-connector tabs list --json

Use these helpers when the task depends on the currently focused tab or a specific returned tab:

browser-connector tabs selected --json
browser-connector tabs get "<tabRef>" --json

If setup or doctor says the extension is stale after a local build or package update, reload it from the CLI:

browser-connector extension reload --reason "refresh extension after update" --json

3. Choose the target tab from the returned `tabRef`, title, URL, and active state. Never guess a `tabRef`.

4. Claim the tab:

browser-connector tabs claim "<tabRef>" --reason "<why this tab is needed>" --json

5. Read the page:

browser-connector page snapshot --lease "<leaseId>" --json

When locating a button, link, input, or custom clickable element without relying on screenshots, prefer structured candidates before choosing a selector:

br