cmux-browser

Source excerpt starting at line 1.

1# Browser Surface Discovery2 3Surface-bound existing-surface browser commands need an explicit surface4handle. The CLI also has a small, explicit global-verb allowlist (for example5`identify`, `devtools`, `design-mode`, `zoom`, `history`, and creation/import6verbs); those commands may omit a handle according to `SKILL.md`. Find a7surface-bound handle with read-only topology commands; never select or focus a8workspace just to make an implicit target work.9 10## Caller workspace11 12Start with the context of the terminal that launched the agent:13 14```bash15cmux identify --json16if [[ -n "${CMUX_WORKSPACE_ID:-}" ]]; then17  cmux tree --workspace "$CMUX_WORKSPACE_ID" --json18else19  # With no caller anchor, use the server's current context after identify.20  cmux tree --json21fi22```23 24`CMUX_WORKSPACE_ID` is the caller anchor, not necessarily the workspace visible25on screen. If it is unavailable, use `cmux identify --json` and state that the26current server context is being used.27 28For one known workspace, list its panes/surfaces without selecting it:29 30```bash31cmux --json list-pane-surfaces --workspace workspace:N32```33 34## Browser in any workspace or window35 36`tree --all --json` is the non-focus-changing global inventory. The following37filter prints only topology refs, not page titles or URLs:38 39```bash40cmux tree --all --json \41  | jq -r '42      .windows[]? as $window43      | $window.workspaces[]? as $workspace44      | $workspace.panes[]? as $pane45      | $pane.surfaces[]?46      | select(.type == "browser")47      | [$window.ref, $workspace.ref, $pane.ref, .ref]48      | @tsv'49```50 51Pick the surface by the workspace/pane the user named, or by a URL/title only52when the user supplied enough context to disambiguate it. For URL/title-only53context, use this exact-match filter; it emits only the unique surface ref and54does not print the matched metadata:55 56```bash57MATCH_FIELD="url" # use "title" when matching a page title58MATCH_VALUE="${BROWSER_URL_OR_TITLE:?set BROWSER_URL_OR_TITLE without logging it}"59SURFACE="$(60  cmux tree --all --json |61    jq -r --arg field "$MATCH_FIELD" --arg value "$MATCH_VALUE" '62      [63        .windows[]? as $window64        | $window.workspaces[]? as $workspace65        | $workspace.panes[]? as $pane66        | $pane.surfaces[]?67        | select(.type == "browser")68        | select((if $field == "url" then (.url // "") else (.title // "") end) == $value)69        | .ref70      ] as $matches71      | if ($matches | length) == 1 then $matches[0]72        elif ($matches | length) == 0 then error("no matching browser surface")73        else error("multiple matches; use workspace/pane context")74        end'75)"76if [[ -z "$SURFACE" ]]; then77  printf '%s\n' 'no uniquely matching browser surface; provide workspace/pane context' >&278  exit 179fi80cmux browser --surface "$SURFACE" get url81```82 83Do not print or store raw authenticated-page metadata unnecessarily.84 85## Inspect the chosen surface86 87```bash88SURFACE="surface:N"89cmux browser --surface "$SURFACE" get url90cmux browser --surface "$SURFACE" get title91cmux browser --surface "$SURFACE" tab list --json92cmux browser --surface "$SURFACE" snapshot --interactive93```94 95These inspection commands do not focus the browser or its workspace. Avoid96`select-workspace`, `focus-pane`, `focus-panel`, `focus-webview`, and other97focus-intent verbs unless the user explicitly asked to change visible focus.98 99## Stale handles and help drift100 101Surface refs can change when a tab is closed/replaced or a browser is restored.102If a previously valid handle is rejected, run `cmux tree --all --json` again and103reselect from the authoritative topology. Never fall back to a focused surface104or a guessed numeric index.105 106When installed documentation and the binary disagree, stop and refresh the107contract before continuing. The installer is pinned to the reviewed `skills`1081.5.23 release:109 110```bash111cmux browser --help112cmux --version113npx --yes skills@1.5.23 add manaflow-ai/cmux --global --yes --skill cmux-browser --agent claude-code codex --copy114```115 116An already-running agent may have cached the old skill; start a fresh session117after the install when needed.118