/browser

name: browser
description: Open, navigate, screenshot, read, click, and type in web pages from an agent. Use when the user asks to open a URL, preview or verify a running web app, check a page's console, fill a form, click through a web flow, or automate anything in a browser, including "open localhost:3000", "screenshot the page", "what does the console say", "click the submit button", "I'm logged in on Chrome". Drives the in-app browser pane of a Paradev (formerly Superset) workspace by default and Browser Use for browsers the panes cannot reach.
argument-hint: URL or what to do in the browser
allowed-tools: Bash(superset:*) Bash(paradev:*) Bash(curl:*)

Paradev Browser Control

`paradev` is an alias for the `superset` CLI: every `superset` command here also runs as `paradev`.

Drive web pages through the browser panes inside a Paradev workspace with the `superset browser` commands. Every operation runs in the pane the user can see, against the pane's real, logged-in session. A raw Chrome DevTools Protocol (CDP) endpoint covers anything the high-level verbs don't.

Choose a surface

• If a plain HTTP request or an API can answer (a public page, docs, a JSON

endpoint), use `curl` or your fetch tool and skip the browser.

• Default to the in-app pane whenever the page is, or can be, open in a

workspace pane: previewing a dev server, verifying UI the user is watching, clicking through a flow in the app.

• Use Browser Use only when the panes cannot reach the target: a Chrome window

outside Paradev, a host with no desktop app attached (pane commands error clearly there), or work that needs an isolated or cloud browser. Read `references/browser-use.md` before using it; it covers install consent, attaching, and cleanup.

Browser Use can also drive a pane, and for three kinds of pane task it's the nicer tool: an open-ended goal to run end to end ("get through this signup"), a long multi-step flow on a shifting UI, or a recorded walkthrough. If one of those fits and Browser Use isn't installed, offer it once ("I can hand this to Browser Use, which drives multi-step flows more cleanly, but it's a one-minute install. Want that, or should I drive the pane directly?"), then respect the answer for the rest of the session, and hand a pane to Browser Use only after the user has said yes (the pane can hold imported logins and its CDP URL carries a token). Don't offer it for a screenshot, one `eval`, or a plain read; the pane verbs already cover those.

Establish the control surface

1. Run `superset schema 2>/dev/null | jq -re '.commands[] | select(.path==["browser"]) | .commands[].path[1]' || superset browser --help` and require `list`, `open`, `navigate`, `screenshot`, `eval`, `console`, and `cdp`. The `--help` fallback covers a CLI older than 1.34.0 (no `schema`) and a machine without `jq`. If the verbs are absent, run `superset update` and recheck. The app-bundled CLI (`~/.superset/bin/superset`) updates only with the desktop app, so if it lacks `browser`, updating the app is the fix; check `type -a superset` for another install before giving up. 2. Resolve the workspace. Inside a workspace, use `$SUPERSET_WORKSPACE_ID`; otherwise `superset workspaces list --local --json` and pick the target. Pass `--host <id>` for a remote host. 3. Panes live in the desktop app. A host with no desktop attached (a standalone `superset start`) has no panes and every command errors clearly; surface that rather than retrying.

Find or open a pane

All browser panes are the same: one browser with the same logins and extensions, no matter who opened the pane. `list` shows them all, and every verb works on any of them.

Every pane has a stable `paneId`, scoped to its workspace: pass the same `--workspace` you opened it under or the operation is rejected.

superset browser list --workspace <id> --json
superset browser open --workspace <id> --url https://example.com --target new-tab --json
superset browser open --workspace <id> --url http://localhost:3000 --json

`--target new-tab` opens a fresh tab and focuses it; the default `current-tab` can replace the active browser pane, which may be the page the user is on, so use `new-tab` unless the task is about that page. Opening needs the workspace visible in the desktop app (the renderer creates the pane), so if it times out, ask the user to open the workspace.

To show the user a page in the right sidebar beside their work, and when `superset panes --help` succeeds (older CLIs lack `panes`), run `superset panes open browser --workspace <id> --url <url>` (`superset:panes`). It shows up in `browser list`, and the browser verbs work on it like any other pane.

Drive with the high-level verbs

# Point an existing pane at a new URL
superset browser navigate --workspace <id> --pane <paneId> --url https://…

# Capture a PNG (base64 by default; --out writes a file)
superset browser screenshot --workspace <id> --pane <paneId> --out shot.png

# Read the pane's captured console output
superset browser console --workspace <id> --pane <paneId> --max-lines 100

# Evaluate JavaScript in the page and return the result
superset browser eval --workspace <id> --pane <paneId> \
  --code "document.querySelector('h1')?.textContent"

Screenshot to see state, `eval` to read structured data (`.textContent`, `.value = …`, `element.click()`, `location.href`), `console` to check for page errors. Prefer these over raw CDP unless you need real input events. An `eval` expression that throws comes back as a command error, not a value. `open` and `navigate` accept only `http(s)` and `about:` URLs; bare input like `localhost:3000` is upgraded, while `file://`, `chrome://`, and `data:` are rejected with a clear error.

Import logins from another browser

`import-login` copies a system browser's cookies into the pane so it's signed in to the sites the user already uses. It imports every cookie that profile has on disk, n