@sightmap/agent-browser

@sightmap/agent-browser is a sightmap-aware wrapper around Vercel’s agent-browser CLI. It adds four sightmap-aware commands (snapshot, match, act, network) that read your .sightmap/ corpus and enrich the agent-facing output with component names, view memory, and request annotations. Every other command — including agent-browser’s -p <provider> flag for hosted Chrome — passes through unchanged.

This is the shell-invocation alternative to MCP, built on Vercel’s CLI instead of Playwright’s. Same enriched snapshots as @sightmap/mcp, now portable across the agent-browser provider ecosystem: Browserless, Browserbase, Kernel, and anything else agent-browser learns to drive. Like its Playwright sibling, this wrapper covers browser-driving and enrichment only — curation tools (proposal workflow, view CRUD) live in MCP.

Install

pnpm add -D @sightmap/agent-browser agent-browser
agent-browser install   # downloads Chrome on first run

agent-browser is a peer dependency. sightmap-agent-browser shells out to it for browser primitives, so it has to be on PATH (or installed in the same node_modules). The one-time agent-browser install step pulls Chrome — same flow as playwright install.

Usage

sightmap-agent-browser [global flags] <command> [args...]

Global flags

Flag	Purpose
-s, --session NAME	Named agent-browser session. Default "default".
--sightmap-dir DIR	Directory of sightmap YAML files. Default .sightmap.
--json	Emit JSON instead of human-readable text.

The .sightmap/ directory is loaded per invocation from --sightmap-dir, resolved against the current working directory. There is no daemon and no cache — every command re-reads the corpus, so edits to .sightmap/ are picked up immediately. Override --sightmap-dir when invoking from outside the project root:

sightmap-agent-browser --sightmap-dir /path/to/repo/.sightmap snapshot

Sightmap-specific commands

Four commands consume .sightmap/ and produce enriched output. Everything else falls through to agent-browser.

snapshot — enriched a11y snapshot

Captures an ARIA snapshot from the current page and annotates it with the matched sightmap view, view memory, and the sightmap components present on the page (with live matchCount).

$ sightmap-agent-browser snapshot
View: SearchResults (route /search)
  memory:
    - paginated; load-more button at bottom
Components:
  - SearchBar (global) — 1 match
  - ResultCard (view) — 12 matches
      memory: clicking opens detail in a new tab

--- ARIA snapshot ---
- main:
  - heading "Results for 'sightmap'" [level=1]
  ...

Pass --json for the structured EnrichedSnapshot plus the raw ARIA text.

match URL — show the matching sightmap view

Pure query: resolves a URL (or pathname) against the loaded sightmap and prints the matched view, applicable components, and known requests. No browser is launched.

$ sightmap-agent-browser match /list/abc123
View: ListDetailScreen (route /list/*)
  memory: id is opaque; do not parse
Components:
  - BottomTabBar (global)
  - ListCard (view)
Requests:
  - GET /api/list/:id → fetchList

This is the same matcher @sightmap/sightmap exposes, surfaced through the agent-browser wrapper for convenience.

act NAME — resolve a component name to a selector

Resolves a sightmap component name to its primary selector (plus any fallbacks). Prints the selector to stdout so it can be piped into another agent-browser command.

$ sightmap-agent-browser act SubmitButton
[data-testid="submit"]
# fallbacks: button[type="submit"]

Exits non-zero if the component name is unknown. Pass --json for the full resolution result.

network — annotated network requests

Pulls recent network requests from the current session and tags any that match a requests: entry in the sightmap, attaching request memory.

$ sightmap-agent-browser network
[GET] https://example.test/api/list/abc → 200  [fetchList]
    memory: returns 404 for archived lists; treat as "not found"
[POST] https://example.test/api/track → 204

Passthrough

Anything that isn’t one of the four sightmap-specific commands is forwarded to agent-browser verbatim, preserving the session flag:

sightmap-agent-browser open https://example.test
sightmap-agent-browser click @e3
sightmap-agent-browser screenshot page.png
sightmap-agent-browser close

The upshot: sightmap-agent-browser is a drop-in for agent-browser. You only opt into the sightmap-aware behavior on the four commands above; everything else still works exactly as agent-browser documents it.

Hosted browser providers

agent-browser’s -p <provider> flag picks a hosted Chrome backend instead of the local one. The flag passes through sightmap-agent-browser unchanged. The provider binds to the session on open, and all subsequent sightmap-aware commands inherit it:

sightmap-agent-browser -p browserless -s demo open https://example.test
sightmap-agent-browser -s demo snapshot   # runs against the browserless-hosted browser
sightmap-agent-browser -s demo close

Sightmap layers above whichever provider you pick — Browserless, Browserbase, Kernel, or the local Chrome agent-browser install set up. No extra wrapper code, no extra cost. If you switch providers next quarter, your .sightmap/ corpus and agent prompts don’t change.

Sessions

agent-browser uses named sessions to keep a browser context alive across invocations. sightmap-agent-browser honors the same flag:

sightmap-agent-browser -s checkout open https://shop.test
sightmap-agent-browser -s checkout snapshot
sightmap-agent-browser -s checkout network
sightmap-agent-browser -s checkout close

If you don’t pass -s/--session, the session is "default". Run parallel flows by giving them distinct session names.

vs. agent-browser direct

You can use agent-browser without this wrapper — it’s a perfectly good CLI on its own. The wrapper buys you four enriched commands and nothing else; the rest of the surface is identical. The trade-off:

	sightmap-agent-browser	agent-browser (direct)
Snapshot output	annotated with view + component names	raw a11y tree
act by component name	yes	no — agent works out selectors itself
Network log	tagged with sightmap request memory	raw requests
-p <provider>	passes through	native
Everything else	passes through	native

If you’re not curating a .sightmap/ yet, start with the quickstart — the enrichment commands need a corpus to enrich against.

vs. @sightmap/playwright

Both are sightmap-aware shell wrappers. They differ only in their browser backend:

	@sightmap/agent-browser	@sightmap/playwright
Wraps	agent-browser (Vercel)	@playwright/cli
Hosted Chrome	yes, via -p <provider>	local only
Sightmap-aware commands	snapshot, match, act, network	snapshot, match, act, network
Passthrough	full agent-browser surface	full @playwright/cli surface

Pick the wrapper whose underlying CLI your agent already knows. The enriched-command surface is identical.

See also

• @sightmap/playwright — sister wrapper over @playwright/cli.
• @sightmap/mcp — the MCP-server alternative with the curation tool family.
• @sightmap/core — the underlying matcher, lint, and validate library. Same semantics, no browser.