sightmap browser manages the Chrome for Testing session that every live command relies on. A session is one Chrome instance per site, recorded in .sightmap/.session, exposing its DevTools endpoint on localhost:7892 (the default --addr) and — when started with browser start — a sightmap HTTP server on port 7891 that feeds the in-browser overlay extension. This page documents the session lifecycle: install, start, launch, stop, status, navigate, eval, and clear-storage.
This page covers session management only. For acting on the page —
click, fill, screenshot, bounds, tab management — see Page interaction. For capturing annotated component trees, see Capturing pages. Page-affecting commands also accept --addr and --tab; see the shared conventions.browser install
Downloads the latest stable Chrome for Testing into ~/.sightmap/browsers/ and prints the path to the installed binary. Idempotent: if the current stable version is already installed, it prints the path and exits 0. Takes no flags.
browser start
The everyday session command. start launches Chrome, starts the sightmap HTTP server (default port 7891) that serves your compiled corpus, and loads the overlay extension — which is embedded in the binary and auto-extracted to ~/.sightmap/extension/ on first start, no flag needed. The server hot-reloads the corpus whenever you edit YAML under .sightmap/, so the overlay always reflects your latest edits. start runs in the foreground until you press Ctrl-C, which stops Chrome and the server together.
Run it from the site directory (the one containing .sightmap/), typically in a second terminal or as a background job.
If Chrome is already running for this site, Thread that ID through as
start does not launch a second instance — it opens a new tab in the existing session and prints that tab’s ID:--tab on every subsequent command so concurrent agents never drive each other’s tab.browser launch
A bare Chrome launcher: starts Chrome with its DevTools endpoint only — no sightmap server, and no overlay extension unless you pass --extensions. Unlike start, launch returns immediately and leaves Chrome running detached; it prints the chosen CDP port to stdout so scripts can capture it. Use launch when you want a plain CDP session without the overlay, or use the --launch flag on analysis commands to do this implicitly.
launch refuses with a session is already running on port 7892 — run browser stop first, or browser status to inspect it.
browser stop
Stops the session’s Chrome — terminating the whole process group, falling back to reaping by profile directory — and removes the session file once nothing is left alive. Takes no flags.
no active session and exits 0.
browser status
Reports session health. status probes the CDP endpoint rather than trusting the .session file, so it detects dead sessions: when Chrome is gone it prints ✗ unreachable, removes the stale session file, and tells you to run browser start again. It also lists every open content tab with a ready-to-paste --tab flag. Takes no flags.
○ no session. If a Chrome process for the site’s profile is still alive without a session file, it reports ⚠ orphan and points you at browser stop to reap it.
browser navigate
Navigates the session to a URL and waits for the page to load. The URL is a positional argument. After a server-side redirect, navigate prints the final URL so you know where the page actually landed.
browser eval
Evaluates a JavaScript expression in the page context and prints the result — pretty-printed when it is a JSON object or array. The script is a positional argument.
Only JSON-serializable values come back. A DOM element reference — document.querySelector(...) by itself — returns an error; extract the value you need instead (document.querySelector('h1')?.textContent).
browser clear-storage
Wipes session state: clears all cookies — including httpOnly cookies that page JavaScript cannot touch — and the origin’s storage (localStorage, IndexedDB, service workers, caches). It is the programmatic equivalent of Chrome DevTools Application → Clear storage, and the reliable way to reset a logged-in session to a clean slate.
Typical flow
1
Install the browser once
sightmap browser install downloads Chrome for Testing to ~/.sightmap/browsers/.2
Start the session
From the site directory,
sightmap browser start — note the --addr and --tab values it prints.3
Check health
sightmap browser status confirms ● running and lists open tabs.4
Navigate and work
sightmap browser navigate 'https://...', then capture and interact (Capturing pages, Page interaction).5
Stop when done
Ctrl-C in the
start terminal, or sightmap browser stop from anywhere in the site directory.