Sightmap Browser Commands: Managing Chrome Sessions

sightmap browser manages the Chrome for Testing session used by live commands. Sightmap records the session in .sightmap/.session. By default, Chrome exposes its DevTools endpoint on localhost:7892; browser start also runs the Sightmap HTTP server on port 7891 for the overlay extension.

This page covers session management. See Page interaction for click, fill, screenshot, bounds, and tab management. See Capturing pages for annotated component trees. Page 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.

sightmap browser install

Resolving latest Chrome for Testing (Stable)...
  version: 151.0.7922.47  platform: mac-arm64
Downloading https://storage.googleapis.com/chrome-for-testing-public/151.0.7922.47/mac-arm64/chrome-mac-arm64.zip
    5%  8 / 178 MB     25%  44 / 178 MB     50%  89 / 178 MB     75%  133 / 178 MB    100%  178 / 178 MB
Extracting...
Installed: /Users/you/.sightmap/browsers/chrome-151.0.7922.47/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing
/Users/you/.sightmap/browsers/chrome-151.0.7922.47/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing

The final line is the binary path on stdout, so scripts can capture it; progress goes to stderr.

`browser start`

start launches Chrome, starts the Sightmap HTTP server, and loads the overlay extension. The extension is embedded in the binary and extracted to ~/.sightmap/extension/ when needed. The server recompiles the corpus after YAML changes under .sightmap/. start runs in the foreground until you press Ctrl-C, which stops Chrome and the server. The start daemon owns the session: it is the only way to launch Chrome for sightmap, and every live command attaches to it. It also runs the console/network collector that buffers browser activity for the console and network commands, so those need a running start session. Run it from the site directory (the one containing .sightmap/), typically in a second terminal or as a background job. start creates .sightmap/ if it is absent and records the session at .sightmap/.session; if it cannot persist that file it fails loudly rather than running sessionless. Every other command finds the session through this file, keyed by --sightmap-dir — so with no session file a command falls back to the default CDP port and warns, since a session answering there may belong to a different corpus or agent. Pass --addr to target a specific session explicitly.

Flag	Default	Description
`--port`	`7891`	Sightmap HTTP server port (`0` = auto-allocate)
`--cdp-port`	`7892`	Chrome remote debugging port (`0` = auto-allocate)
`--sightmap-dir`	`.sightmap`	Path to the corpus directory
`--extensions`	embedded overlay	Comma-separated extension paths to load instead of the embedded overlay extension
`--url`	none	Navigate here after launch
`--profile`	per-site directory under `~/.sightmap/profiles/`	Chrome user data dir
`--headless`	off	Run Chrome headless
`--wait`	`0`	Seconds to wait after navigation

cd sites/shop.example.com/
sightmap browser start --url 'https://shop.example.com'

[serve-sightmap] listening on http://:7891
● ready  port=7891  cdp=7892  pid=84210  tab=8A3F0C7D2B1E4F6A9C8D7E5B3A2F1E0D
  Addr: --addr localhost:7892
  Tab:  --tab 8A3F0C7D2B1E4F6A9C8D7E5B3A2F1E0D  (pass this on commands once other agents open tabs here)
  Press Ctrl-C to stop.

If Chrome is already running for this site, start opens a new tab in the existing session and prints that tab’s ID:

● tab    cdp=7892  tab=F2B71D9E4C8A2B5F0E3D6C1A9B8E7F4A
  Chrome was already running for this site; opened a NEW tab for you.
  Pass --tab F2B71D9E4C8A2B5F0E3D6C1A9B8E7F4A on EVERY command this session — other tabs belong to other agents.

Pass that ID as --tab on every subsequent page command.

`browser stop`

Stops the session’s Chrome process group. If needed, it finds remaining processes by profile directory. It removes the session file after Chrome stops. Takes no flags.

sightmap browser stop

stopping Chrome (pgid 84210, port 7892)...
stopped

With no session running it prints no active session and exits 0.

`browser status`

Reports session health by probing the CDP endpoint and lists each open content tab with its --tab value. If Chrome is gone, it prints ✗ unreachable, removes the stale session file, and tells you to run browser start again.

Flag	Default	Description
`--tab`	none	Mark this tab in the status output

sightmap browser status

● running  cdp=7892  pid=84210
  profile: /Users/you/.sightmap/profiles/shop.example.com
  tabs (2):
    --tab 8A3F0C7D2B1E4F6A9C8D7E5B3A2F1E0D  https://shop.example.com/
    --tab F2B71D9E4C8A2B5F0E3D6C1A9B8E7F4A  https://shop.example.com/cart
  multiple tabs open — pass --tab <ID> on page commands to avoid crosstalk.

With no session it prints ○ 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 redirect — server-side or client-side (an SPA auth guard bouncing /login → /, or / → /workspace) — navigate prints the requested and final URLs, so you know where you actually landed.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--tab`	the lone content tab	Target tab ID

sightmap browser navigate 'https://shop.example.com/deals'

navigated to https://shop.example.com/deals
  (redirected to https://shop.example.com/offers)

browser navigate takes a positional URL. It has no --url flag; that flag belongs to browser start. sightmap browser navigate --url 'https://...' treats --url as the URL and fails.

`browser eval`

Evaluates a JavaScript expression in the page context. The script is a positional argument. The command pretty-prints JSON objects and arrays. Only JSON-serializable values can be returned. A DOM element reference such as document.querySelector(...) cannot be returned by value; extract a property such as document.querySelector('h1')?.textContent.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--tab`	the lone content tab	Target tab ID

sightmap browser eval '({url: location.href, title: document.title})'

{
  "title": "Example Shop — Home",
  "url": "https://shop.example.com/"
}

`browser inject`

Injects a script into the page. Where eval runs once in the current document, inject --persist registers the script with the session daemon so it re-runs at the start of every new document, in every tab, for the life of the session — surviving navigations. It is backed by CDP Page.addScriptToEvaluateOnNewDocument, held on the daemon’s session-lifetime connection (a script added over a per-command connection would be dropped the moment that command exits). Handy for polyfills, overlays, and instrumentation or experimentation bundles that must outlive a multi-page flow. Provide the source as an inline positional argument or with --file. --persist also runs the script once in the currently-loaded document (best-effort), since addScriptToEvaluateOnNewDocument only affects future documents.

Flag	Default	Description
`--file`	—	Read the script source from this file instead of an inline arg
`--persist`	`false`	Re-inject on every new document and new tab for the whole session
`--remove`	—	Remove a previously-persisted script by its id
`--list`	`false`	List the scripts currently persisted for this session
`--addr`	`localhost:7892`	CDP address (one-shot run)
`--tab`	the lone content tab	Target tab ID (one-shot run)

--persist, --remove, and --list require a running browser start session, since the registry lives in its daemon.

# Register a bundle that re-applies on every navigation, and print its id.
sightmap browser inject --file ./runtime.js --persist
# inject: persisted as inj-1 — re-injected on every new document; remove with 'browser inject --remove inj-1'

sightmap browser inject --list
sightmap browser inject --remove inj-1

`browser mcp`

Enumerate and call the WebMCP tools a page exposes. A page can declare callable actions to an in-browser agent through document.modelContext (getTools() / executeTool()); mcp list reads them and mcp call invokes one — so you can call a named action instead of driving the UI blind. mcp list distinguishes three states: native WebMCP (a browser-provided document.modelContext), a polyfilled one (provided by a page script), and absent. When absent it fails loudly with the Chrome flags that enable native WebMCP. One tool runs at a single point in time; WebMCP has no cross-navigation tool responses, so if a tool triggers a client-side navigation, re-run mcp list on the new view. Any guidance the tool returns (e.g. a hint toward the next tool) is part of its result. Native WebMCP is behind Chrome flags; start the session with them:

sightmap browser start \
  --chrome-flag=--enable-blink-features=ModelContext,ModelContextTesting \
  --chrome-flag=--enable-features=DevToolsWebMCPSupport

Command	Flags	Description
`mcp list`	`--json`	Enumerate exposed tools (name, description, input schema). `--json` emits the full schemas.
`mcp call <tool>`	`--args JSON`, `--param k=v`, `--json`	Invoke a tool via `executeTool` and print its result. Supply arguments as a JSON object (`--args`) and/or repeatable `--param key=value` pairs (each value parsed as JSON when possible, else a string) layered over `--args`.

Tools return the standard WebMCP CallToolResult envelope ({ content, isError }). mcp call unwraps it — rendering the text/structured content (and any guidance the tool includes) as itself rather than a stringified blob — and exits non-zero when the tool reports isError, so it is scriptable. --json prints the raw envelope verbatim.

sightmap browser mcp list
# WebMCP (polyfilled) — 1 tool(s):
#   search — Search flights by route

sightmap browser mcp call search --args '{"query": "ATL to LHR"}'
sightmap browser mcp call search --param query="ATL to LHR"   # equivalent

Both accept --addr and --tab like the other page commands.

`browser clear-storage`

Clears all cookies, including httpOnly cookies, and clears storage for one origin. Origin storage includes localStorage, IndexedDB, service workers, and caches.

Flag	Default	Description
`--addr`	`localhost:7892`	CDP address
`--tab`	the lone content tab	Target tab ID
`--origin`	current page origin	Origin whose storage to clear

sightmap browser clear-storage

clear-storage: ✓ httpOnly cookies cleared
clear-storage: ✓ origin storage cleared (https://shop.example.com)
clear-storage: done — navigate to homepage and wait before accessing protected pages

Typical flow

Install the browser once

sightmap browser install downloads Chrome for Testing to ~/.sightmap/browsers/.

Start the session

From the site directory, run sightmap browser start. Note the --addr and --tab values it prints.

Check health

sightmap browser status confirms ● running and lists open tabs.

Navigate and work

sightmap browser navigate 'https://...', then capture and interact (Capturing pages, Page interaction).

Stop when done

Ctrl-C in the start terminal, or sightmap browser stop from anywhere in the site directory.

Overview

Browser

Capture and coverage

Selectors and corpus

Integrations

Sightmap Browser Commands: Managing Chrome Sessions

`browser install`

`browser start`

`browser stop`

`browser status`

`browser navigate`

`browser eval`

`browser inject`

`browser mcp`

`browser clear-storage`

Typical flow

​browser install

​browser start

​browser stop

​browser status

​browser navigate

​browser eval

​browser inject

​browser mcp

​browser clear-storage

​Typical flow

`browser install`

`browser start`

`browser stop`

`browser status`

`browser navigate`

`browser eval`

`browser inject`

`browser mcp`

`browser clear-storage`

Typical flow