browser-skill

Drive the user's real Chromium browser (with their logins and cookies) through the bsk CLI. The extension opens an isolated Agent Window for automation; the user's normal windows stay protected unless you explicitly borrow a tab.

When to use

• Open pages, read titles/text, scrape structured data from sites the user can already access
• Fill forms, click through multi-step flows, smoke-test a UI change
• Understand pages with bsk snapshot first; use bsk get-html or bsk screenshot only when the snapshot is insufficient
• Operate on a specific user tab they point you at (after bsk tab borrow)

When NOT to use

• Tasks with no browser involved (files, APIs, databases only)
• Installing or configuring the extension (point the user to setup docs instead)
• Credential harvesting — never run bsk evaluate on banking, SSO, or password-manager pages to extract tokens, cookies, or secrets
• Long-lived control of a user's personal login window — borrow only for the immediate step, then bsk tab return or end the session
• Replacing the user's manual browsing when they only wanted an explanation

Prerequisites

1. bsk on PATH (Rust CLI from browser-skill)
2. browser-skill extension loaded in Chromium and connected (popup shows green)
3. Any bsk command auto-starts background services as needed; use bsk doctor if anything fails

Mandatory workflow

Every automation task must follow this lifecycle. Do not rely on idle timeouts (default session idle is 5 minutes).

1. bsk session start              → capture the 4-letter session id printed on stdout
2. … every tool command …        → always pass --session <id>
3. bsk session stop <id>          → REQUIRED when done (even on error paths)

Optional: bsk session start --browser <instance-id-or-label> when multiple browsers are connected (bsk browsers / error output lists them).

Emergency cleanup: bsk session stop --all or the Agent Window overlay Stop all.

Core interaction loop

Write operations only affect tabs in the Agent Window (or tabs you borrowed into it).

bsk navigate <url> --session <id>
bsk snapshot --session <id>          → aria tree with @e1, @e2, … refs
bsk click @e3 --session <id>          → or bsk fill, bsk select, bsk press
bsk snapshot --session <id>            → again after navigation / DOM change

Refs invalidate after navigation — always re-snapshot before clicking, filling, or selecting on a new page.

Prefer @eN refs from the latest snapshot over raw CSS selectors. Use --ref / --selector when ambiguous (bsk click --help).

Observation priority

Start with bsk snapshot to understand page structure, text, controls, and element refs. Only escalate when the latest snapshot cannot answer the question:

1. bsk snapshot — default for page understanding and interaction planning
2. bsk get-html — when hidden DOM, metadata, or markup details are required
3. bsk screenshot — when visual layout, canvas/image content, or styling cannot be inferred from the snapshot. Use --ref @eN (from the latest snapshot) to crop to one element; omit --ref for the full visible tab.

Do not call bsk get-html or bsk screenshot first just to inspect a page.

Sandbox rules

Global flags

Command-specific flags (timeouts, --tab-id, --wait-until, …): bsk <cmd> --help

CLI command reference (one line each)

Details and flags: bsk <cmd> --help

Diagnostics

Session

Tabs (require --session <id>)

Observation (require --session unless noted)

Navigation

(bsk navigate back / bsk navigate forward are equivalent subcommands.)

Interaction

Scripting & timing

Ask the human for help — bsk request-help

When a step needs a human (captcha, login, OTP) or you want the user to confirm an important action, pause and ask:

bsk request-help --session <id> --prompt "Solve the captcha, then click Continue" \
  --title "Captcha required" --target @e7 --target "#submit" --timeout 5m

• --prompt (required): what the user should do.
• --title (optional): custom title for the overlay panel. When omitted, the extension shows its default localized title.
• --target (repeatable): a snapshot ref (@e7) or CSS selector (#submit) to scroll to and flash-highlight. Strongly recommended — whenever the prompt refers to a concrete element (a button to click, a field to fill, a checkbox to toggle), pass its @eN ref / selector so the user is guided straight to the right spot instead of hunting for it. For interaction scenarios, always include the relevant target(s); reserve a prompt with no --target for cases where there is genuinely no specific element to point at (e.g. "wait for the page to finish loading").
• --timeout (default 5m): how long to wait.

The target tab is brought to the foreground; the page stays interactive while the agent control mask is hidden. The call blocks until the user acts. The result outcome is one of:

• continued — the user finished and clicked Continue (treat as confirm).
• cancelled — the user clicked Cancel (treat as reject/abort).
• timed_out — nobody acted within the timeout.
• navigated — the page navigated while waiting (full reload or SPA URL change). Snapshot refs are stale; run bsk snapshot on the new page, then decide whether to call bsk request-help again.

note carries any text the user typed back. resolved_targets reports which refs/selectors matched a live element.

Error handling

Exit codes (echo $? after bsk …)

Human errors print error: + hint: on stderr; --json includes code, message, hint, exit_code.

When to run diagnostics

Always bsk session stop <id> in a finally-style path so the Agent Window closes and borrowed tabs return.

Red lines

1. No token theft — do not bsk evaluate on sensitive sites to read localStorage, cookies, or auth headers for exfiltration.
2. No long borrow — do not leave a user's personal tab in the Agent Window across unrelated tasks.
3. No skip stop — always bsk session stop <id>; never assume idle timeout will clean up.
4. No observe escalation before snapshot — use bsk snapshot first; only use bsk get-html or bsk screenshot when the snapshot is insufficient. Element screenshots (--ref @eN) still require a fresh snapshot ref — never skip snapshot just to grab a visual.
5. evaluate is powerful and risky — use only when snapshot + click/fill/select cannot suffice; never on credential surfaces.

More detail for any command: bsk <cmd> --help