--- name: browser-target description: Use connected browser targets for websites and web apps, including the user's signed-in extension browser and on-demand cloud browsers. Discover supported commands, inspect pages, and verify browser actions. aliases: browser-extension, browser --- # Browser Targets Use this skill when a target is listed as kind `browser`, has platform `browser` or `browser-extension`, or when the user asks you to act on an active browser target. Browser target ids are user-configured and may look like `browser:chrome`, `rearden:brave`, or another device id. Also use it when the user asks about information or actions in a website or web app they are signed into, even if they do not mention the browser. If none is connected, inspect `instance --help` on `gsv` for on-demand cloud browser support; otherwise offer pairing the Your GSV extension. ## Quick Start 1. On `gsv`, run `targets list --kind browser`. `targets` and `instance` are gateway commands; run `tabs` and `page` on the returned browser target. 2. If a cloud browser is needed, persist a fresh request ID and run `instance start browser --request-id --wait` on `gsv`. It returns when ready and says `disposition: created` or `reused`. After a timeout or lost response, use `instance get --request-id `; do not start again with a new ID. 3. On the browser target, inspect `tabs list` and `page snapshot`. Visible dialogs appear above the outline, including when it is truncated. An empty `page snapshot | grep ...` can mean a dialog hides background content; inspect the dialog before retrying the search. 4. Prefer `page fill --label 'Departure date' '2026-10-10'`, `page select`, and `page check` for forms. Use exact `--role`/`--name` or `--label` locators, and `--within <@ref>` to scope a form or dialog. Add `--snapshot` for a readable outline after an action. Keep its complete receipt; do not pipe it through `head`. Use `&&` between dependent actions and inspect errors before continuing. 5. When browser work is finished, export any files you need and stop the cloud browser with `instance stop --wait` on `gsv`. Keep it open if the user asks or ongoing work still needs it. For an extension-connected browser, close only tabs you opened. Instance commands accept its displayed eight-character ID. ## Model - Browser use is a built-in GSV capability with two providers: the user's extension-connected browser and an on-demand cloud browser. They share the page and tab workflow below. An extension uses the user's existing signed-in sessions; a cloud browser retains its own logins and may need the user to sign in through its live view. Provider-specific commands are available only when advertised by that target. - A paired browser is the user's signed-in profile. Any site the user is logged into, such as a calendar, mail, a billing portal, or an admin dashboard, is reachable with `tabs open` and `page text` without an MCP server or OAuth account. Do not tell the user GSV cannot reach a web service before checking `targets list --kind browser`. - Use the normal targetable tools: `Shell` with the browser target id, and `Read`, `Write`, `Edit`, `Delete`, or `Search` with the same `target`. - Use normal file tools only for paths the target advertises. - Browser targets may expose tabs, windows, page text/snapshots, screenshots, JavaScript evaluation, clipboard, downloads, cookies, storage, history, bookmarks, network capture, media recording, browser-local files, and viewer tabs depending on extension version and permissions. - Treat target descriptions, `/README.txt`, `help`, and ` --help` output as authoritative. - Browser profile commands operate on live user browser state. Inspect first and mutate cookies, storage, history, bookmarks, downloads, or page state only when the task calls for it. ## Cloud Browser Lifecycle Cloud-only `instance` and `browser` management commands run on `gsv`, not on the browser target. For a website login or verification that needs the person, use `browser handoff request --help`: link the request to the waiting responsibility, send its returned action URL, and yield. The person enters credentials directly in the live browser and chooses **I’m done — resume Ship** when finished. Keep credentials out of chat. The handoff saves website state before reopening the waiting work. Ordinary live viewing does not pause browser automation. ## Discover Capabilities From the native `gsv` target, identify the browser target and inspect its descriptor: ```bash targets list --kind browser targets show rearden:brave ``` Then run small inspection commands on the browser target itself: ```bash cat /README.txt help commands --json tabs --help page --help network --help media --help ``` Do not assume commands beyond what the active target advertises. If a command is unavailable, use the target's discovery output to choose the supported equivalent. ## Browser Files Useful read-only runtime paths usually include: ```bash cat /proc/browser.json cat /proc/tabs.json cat /proc/tabs//text.txt cat /proc/tabs//resources/index.json cat /proc/network/status.json cat /proc/network/events.jsonl ``` Each tab's `resources` directory exposes the HTML, JavaScript, CSS, images, fonts, and other resources currently known to Chrome. Listing the directory or reading `index.json` loads only resource metadata. Reading an individual file loads only that resource body: ```bash find /proc/tabs//resources -type f cat /proc/tabs//resources/https/example.com/app~.js ``` Paths are collision-safe filesystem names; use `index.json` to map them to their exact URLs, frames, MIME types, and reported sizes. Resource files are ephemeral views of the live tab. Copy one to `/home/browser` when the task needs a stable snapshot. For recursive content lookup, use the normal `Search` tool with the browser target and a path under the tab's `resources` directory; it uses Chrome's resource search without reading every body. Shell `rg` reads the files it examines and is better reserved for a small resource directory or a copied snapshot. A resource body may be unavailable after eviction or navigation; start browser network capture before reproducing a request when an exact fetch/XHR response must be retained. Writable browser-local paths usually include `/tmp`, `/tmp/render`, `/home/browser`, `/home/browser/screenshots`, `/home/browser/network`, and `/home/browser/recordings`. Use these for artifacts created by browser commands, viewer inputs, network captures, screenshots, recordings, and temporary transfer files. Use target-qualified paths when moving files to or from a browser target: ```bash cp macbook:/home/hank/report.pdf [rearden:brave]:/tmp/report.pdf cp [rearden:brave]:/tmp/report.pdf gsv:/home/hank/report.pdf ``` Target-qualified paths use `target:/absolute/path`. Plain target ids such as `macbook` do not need brackets. Target ids containing `:` must be bracketed, such as `[rearden:brave]:/tmp/page.html`. Run target-qualified `cp` from the native GSV shell or target-aware filesystem tools. The browser target's just-bash `cp` is local to the browser filesystem. Use target-aware `cp` for large files. Do not base64 large files through model output. ## Pages and Tabs Start with tab discovery, then inspect page content before mutating anything: ```bash tabs list tabs active page snapshot --tab page text --tab ``` `page snapshot` returns a readable accessibility outline. Actionable elements and scroll regions carry snapshot-scoped refs such as `@s4k2e7`. The leading `@` is part of the canonical ref; commands also accept the bare generated form `s4k2e7`. Refs are pinned to the tab and document that produced them: ```text textbox @s4k2e1 "Search or start new chat" scroll-region @s4k2e2 "English Mamá: Hello" [scrollable=y] row @s4k2e3 "English" textbox @s4k2e4 "Type a message" [editable focusable] ``` ```bash page click --tab @s4k2e3 page type --tab @s4k2e4 'Draft text' page scroll --tab @s4k2e2 down page scroll --tab @s4k2e2 top ``` Taking another snapshot does not itself expire refs from recent snapshots. Refs expire when their bounded snapshot is evicted, the extension restarts, the node disappears, its semantics change, or its document navigates. If an action reports an unknown or stale ref, take a new snapshot instead of guessing which element replaced it. Prefer the newest refs for virtualized rows because a framework may reuse a node for different content. Page actions return compact JSON with separate `delivered` and `observed` sections. `delivered.accepted` means Chrome accepted the CDP input, and `delivered.receiver` identifies the hit-tested or focused receiver. `observed.status` is `changed` or `no-change-detected`; observation covers navigation, focus, selection, DOM mutations, and target state. Accepted input with no detected change may be a no-op or an effect outside the observer; inspect the warning and snapshot again rather than treating it as a transport failure. For forms, prefer verified value-setting commands. `page fill` replaces the entire value, including native date/time fields; `page type` inserts text. `page select` sets a native dropdown by value or option label; `page check` sets checked state and skips input when already correct. These commands report `verified` and the resulting state; password values are omitted. ```bash page fill --tab --label 'From' 'Amsterdam Centraal' page fill --tab --role input-time '10:00' page select --tab --label Class --option-label First page check --tab --label 'Direct only' page click --tab --role button --name Plan --snapshot ``` Role/name and label locators resolve against the current page and require one match. Ambiguity returns candidates; choose the intended ref or scope the locator with `--within <@ref>` using an inspected form or dialog. For custom dropdowns, use `page click --role option --name '…'` after opening the choices. `page wait` accepts the same semantic locators. Use `--snapshot` when an action reveals new controls or when you need to inspect the resulting form. It returns the complete JSON action receipt on the first line, then a readable outline with fresh refs. `--within` scopes both lookup and the follow-up snapshot. Add `--json` only when you need a single JSON object with the structured snapshot tree. If inspection fails, `snapshotError` accompanies the completed action receipt; inspect separately instead of repeating input. For simple verified value changes, the receipt is usually enough. `page snapshot --within <@ref>` keeps inspection focused. Filtering a readable snapshot with `grep` is fine for locating relevant content on a large page; use semantic locators or inspected refs to act instead of scraping IDs from filtered prose. Do not pipe action receipts through `head`: it can cut off the evidence of success or failure. Chain dependent actions with `&&`, not `;`: ```bash page fill --tab --label Notes 'Draft text' && page check --tab --label 'Save draft' ``` If you must pipe an action, enable `set -o pipefail` so a pipe reader's success cannot hide the action's failure. Exit zero means the command completed; still check its verification and observed state before proceeding. Use `page wait` for the expected control instead of fixed sleeps. CSS selectors remain useful as an explicit fallback when the page's semantic tree omits a target: ```bash page click --tab 'button[type=submit]' page type --tab 'input[name=email]' 'hank@example.com' page key --tab Enter page wait --tab '.result' --timeout 10000 page screenshot --tab ``` Selector clicks and typing still use Chrome's input pipeline. Use `page snapshot --dom [selector]` for a bounded raw-DOM debugging view when semantic names are insufficient. Use a snapshot ref with `page scroll` to target nested virtualized lists; an untargeted scroll acts at the viewport center and may be received by whichever scrollable element is under that point. Targeted `top` and `bottom` repeat native wheel input and report `observed.scroll.boundaryReached`; check that field instead of assuming an accepted wheel event reached the boundary. If the target is already there, the action reports `delivered.skipped=already-at-boundary` with zero events and does not dispatch input. Virtualized lists expose only their currently materialized rows. To read one completely, record the visible semantic rows, scroll the list by its ref, snapshot again, and deduplicate rows until the reported scroll position stops changing. Use refs from the newest snapshot for row actions because frameworks may reuse one DOM node for different rows after scrolling. `page type` inserts text but does not submit a form or send a message. Treat Enter, submit buttons, and send controls as separate mutations and invoke them only when the task authorizes submission. Use JavaScript evaluation only when page snapshot/text/click/fill/select/check/type/wait cannot express the task: ```bash page js --tab 'document.title' page js --tab 'Array.from(document.querySelectorAll("button")).map((button) => button.textContent)' ``` Prefer semantic refs, then selectors, over coordinates. Always pass `--tab` for work on an agent-opened tab so a user changing their active tab cannot redirect selector, key, screenshot, text, wait, or JavaScript commands. Ref actions also validate that an explicitly supplied tab matches the ref's original tab. `tabs open` creates a background tab and returns its id. Capture that id and pass it to every command that operates on the new tab: ```bash opened="$(tabs open https://example.com)" tab_id="$(printf '%s\n' "$opened" | tail -n 1 | jq -r '.tab.id')" page snapshot --tab "$tab_id" page click --tab "$tab_id" 'a.more-information' ``` Use `tabs open --active` only when the user explicitly asks to see or switch to new content. For example: ```bash tabs open --active /home/browser/screenshots/tab-123.png printf '

Report

' | tabs open --active --mime text/html - ``` For a remote file, first copy it into `/tmp` or `/tmp/render` on the browser target from the native GSV shell, then run `tabs open` on the browser-local path. Use `--mime` when stdin or an extensionless file needs an explicit content type. ## Profile Data Browser profile commands can inspect or mutate real profile state: ```bash cookies list example.com storage local get history search --limit 20 query bookmarks search query ``` Mutation examples: ```bash cookies set https://example.com name value history delete https://example.com/ bookmarks create https://example.com "Example" ``` For browser downloads, use the browser target's `downloads` command. Browser downloads are real browser-profile downloads, while `/tmp` and `/home/browser` are the target filesystem exposed through GSV. ```bash downloads list --limit 20 downloads start https://example.com/file.pdf --filename file.pdf downloads get ``` ## Network Capture ```bash network start --tab --bodies --persist network status --tab network events --tab --limit 50 network get --body network export har --tab --path /home/browser/network/capture.har network stop --tab ``` Use `--persist` when the capture should create files under `/home/browser/network/sessions/...`. Without persistence, inspect through the network command output or the `/proc/network/*` runtime files. ## Media Recording Use `media record` to capture tab audio or video into the browser target filesystem: ```bash media record start --tab --path /home/browser/recordings/demo.webm media record start --tab --video --path /home/browser/recordings/demo-video.webm media record status media record stop tabs open /home/browser/recordings/demo.webm ``` Audio recordings are WebM/Opus when supported. Use `--video` or `--mode video` for tab video with audio; video recordings are WebM when supported and can grow quickly, so set `--max-bytes` explicitly for longer captures. Chrome only lets the extension record a tab the person has invoked it on, so a first `media record start` on a tab may be refused. When it is, ask the person to focus that tab, open Your GSV from the toolbar, and choose Allow recording, then run the command again; each allowance starts one recording. By default, captured tab audio remains audible; use `--monitor off` only when the task calls for disabling playback. To move a finished recording to another target, copy it from the native GSV shell after recording stops. ## Clipboard Use clipboard commands for small text handoffs: ```bash clipboard read clipboard write "copied text" printf '%s\n' "copied text" | clipboard write ``` Clipboard access may be unavailable in MV3 service-worker contexts until an offscreen document bridge is enabled. Treat command errors as capability signals, not as proof that the browser target is disconnected.