Use to work in an Agent Window with the user's existing logins. User tabs require explicit borrowing. This skill does not install the extension or handle advice-only tasks. Never extract credentials, cookies, tokens, or other secrets.

For remote setup or pairing, follow the remote guide.

Local commands normally auto-start the daemon. If the host terminates background children after each shell call, including on Windows, complete these steps first:

Use the same and on EVERY sandboxed command; environment settings may not persist between shell calls. Keep browser commands sandboxed. For other startup failures, retry once, then use . A local process identity warning permits browser commands when IPC works.

Replace , example refs and values with actual results and task inputs. Every session-scoped command needs ; takes the ID positionally. For unfamiliar commands or flags, consult or instead of guessing; no need to read all help at startup. When following a trace, use its semantic targets and values in order, not its old refs. Stop at the requested goal; a trace grants no additional authorization.

Prefer for text, controls and refs. Navigation invalidates refs; large DOM changes can stale them too. Re-observe before the next interaction. Use refs for iframe/shadow-root targets; CSS selectors search the main document.

Choose the relevant example, using a ref that actually appeared on the page:

bsk click @e3 --session <id>

bsk fill @e3 --value "text" --session <id>

bsk select @e3 --value "option-value" --session <id>

bsk press Enter --ref @e3 --session <id>

bsk hover @e3 --session <id>

bsk scroll-to @e3 --session <id>

bsk wheel --delta-y 600 --session <id>

bsk focus @e3 --session <id>

bsk blur @e3 --session <id>

Use for a static accessibility tree, for exact markup or hidden metadata, and for visual content or requested visual evidence. Do not start with HTML/images just to find ordinary controls; obtain fresh refs before interacting with controls found that way.

There is no default token cap. With , follow a returned / when relevant content remains:

bsk observe --cursor <token> --session <id>

Each page replaces the ref map: use its refs before continuing and never reuse refs from earlier pages. Continuation reads the same capture, without refreshing or hovering; do not combine it with depth changes or hover probing. New observe/ snapshot or changed page identity invalidates continuation; then observe afresh.

List before borrowing, and return the tab as soon as the relevant step ends:

bsk tab list --scope user --session <id>
bsk tab borrow <tab-id> --session <id>
bsk tab return <tab-id> --session <id>

Never invent tab IDs or keep a user tab across unrelated work. Do not repeat pending, denied or timed-out borrows. For , inspect tab/ session state first: the tab may already have moved. Do not bypass an outcome through another browser backend. changes only the confirmation wait (default 60s); custom waits require daemon and extension protocol 1.2+.

The extension's saved Automation settings control borrow confirmation and human help independently; both default on and apply to existing sessions too. Read in or when needed. Deprecated , , and cannot override these settings. Never change browser storage/settings to bypass them. Human-help availability does not require permission for every action or grant extra authority. requires daemon protocol 1.3; update CLI, daemon and extension for full settings support. A feature's version error does not disable other operations.

Remote content reads/actions require task-created or borrowed tabs. Page-opened popups gain no control automatically; an unowned tab inside the Agent Window needs the user to move it to a user window before borrowing. Remote upload/download are unsupported; screenshots work.

With help enabled, request help for login, CAPTCHA, OTP, payment confirmation, consent, or after two attempts make no progress:

bsk request-help --session <id> --prompt "Please complete sign-in" --target @e3

Use a precise prompt and fresh targets; omit when no control fits. Use completion criteria only for a clear, stable success signal.

continued

completed

cancelled

timed_out

disabled

fill_value_mismatch

Navigation alone (including deprecated help outcome ) is not completion. For other errors, follow the returned hint and inspect the current state.

Help disabled: do not request help or re-enable it. Use existing login state, authorized inputs and viable alternatives; disabling help adds no permission and does not remove borrow confirmation or host restrictions. Where authorized, a vision-capable model may attempt graphical verification. Phone-only QR scans, face verification, missing SMS codes or image-only tasks for a text-only model may remain blocked. Report a specific blocker only when inputs/capabilities are missing or viable approaches are exhausted; continue independent work. Do not loop on identical failures, repeat unknown effects or switch backends to bypass limits. On an unrecoverable failure, report the blocker and stop the owned session.

bsk screenshot --session <id> --out viewport.png
bsk screenshot --session <id> --ref @e3 --out element.png --json
bsk screenshot --session <id> --full-page --out page.png
bsk screenshot --session <id> --full-page --scope current --out loaded.png

Screenshots return a local PNG path; view the image to interpret it. replaces an existing file; omitting it uses a temporary path. includes dimensions and byte size. and cannot be combined.

Full-page mode scrolls an ordinary webpage and restores its position/styles. The default follows appended content. Use when capturing the currently loaded range is requested: it stops at the initial document height, even if a loading indicator remains. Later content below that boundary is excluded; report this range rather than claiming all feed entries were loaded. Use a selected, session-controlled tab and stable viewport; targets a tab without selecting it. Internal browser pages, the Web Store, nested scrolling panels and virtualized lists are unsupported. Capture/encoding defaults to 2m; extends it only in full-page mode. Allow the shell enough time for capture plus transfer. Respect cancellation; do not blindly retry endless pages or substitute a viewport image when an older extension rejects full-page capture. Use matching CLI/extension builds. Ctrl-C cancels; failed full-page captures save no partial image. A error means the bottom kept a loading indicator without height growth for 30s; do not simply increase the deadline. Choose only when that range satisfies the request. Keep the capture tab visible: is an environment interruption, while means user input stopped capture. For other failures follow the returned reason and hint; do not work around them by editing the page or stitching screenshots.

For , observe returns text, not pixels. Screenshot that ref when its contents matter; never infer Canvas controls or names from nearby labels. If images cannot be received/understood, explain the limitation, ask for an image-capable model when needed, and continue with available semantics.

To click a point seen in a Canvas image, retain that screenshot's :

bsk click @e3 --capture <capture-id> --image-x <x> --image-y <y> --session <id>

Use ORIGINAL PNG coordinates and dimensions, not resized display/viewport pixels. Captures are single-use, expire after 2m, and are invalidated by ref replacement (observe/snapshot/continuation) or a newer screenshot of that ref. With , the image is view-only: observe and screenshot again before clicking. Counts 1/2, buttons and modifiers work; Canvas fill, IME, drag, hover and HTML extraction do not. Repainting is allowed; changed identity/geometry/hit targets are rejected. Verify the result, using DOM refs for revealed controls; inspect before retrying with a new capture.

bsk upload @e3 --file ./report.pdf --session <id>
bsk download @e3 --out ./report.pdf --session <id>

Upload discloses the file to the site; download accepts site-controlled bytes. Use agent-local paths, not browser-internal staging paths.

Use / for bounded read-only diagnostics; follow returned sequence cursors. affects one tab; restores it. is a last resort: inspect JSON , since a script exception can have CLI exit code 0. Never evaluate secrets. captures user actions; read its help first and never record banking, SSO or password-manager pages. Use to find navigation/history, tab, wait and window commands.