@sightmap/agent-browser

Sightmap-aware wrapper around Vercel's agent-browser CLI. Adds four sightmap-aware commands (snapshot, match, act, network) that consume your .sightmap/ corpus; all other commands forward verbatim to agent-browser — including the -p <provider> flag for hosted Chrome providers.

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).

Usage

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

Global flags

| Flag | Default | Meaning | | --- | --- | --- | | -s, --session NAME | default | Named agent-browser session | | --sightmap-dir DIR | .sightmap | Path to .sightmap/ directory | | --json | false | 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.

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.

$ sightmap-agent-browser -s demo snapshot
View: Example (/**)
  memory:
    - IANA-reserved domain used for documentation examples
Components:
  - Heading (view-scoped) — 1 match

--- ARIA snapshot ---
- heading "Example Domain" [level=1, ref=e1]
- paragraph
  - link "Learn more" [ref=e2]

Pass --json for a structured object including an ariaSnapshot field carrying the raw a11y text (parity with @sightmap/mcp).

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

act NAME — resolve a component name to a selector

Resolves a sightmap component name to its primary CSS selector (plus any fallbacks). Prints the selector to stdout so it can be piped into another agent-browser command. Exits non-zero with a reason for unknown components.

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

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

Any command not listed above forwards to agent-browser verbatim, with --session NAME prepended. This makes sightmap-agent-browser a drop-in upgrade for agent-browser:

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

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 flows through 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.com
sightmap-agent-browser -s demo snapshot   # runs against the browserless-hosted browser

Sightmap layers above whichever provider you pick (Browserless, Browserbase, Kernel, …) — no extra wrapper code needed, no extra cost.

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.

.sightmap/ resolution

Resolved per-invocation, from CWD by default. Override with --sightmap-dir when invoking from outside the project root:

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

Integration tests

Set SIGHTMAP_AB_INTEGRATION=1 to enable the real-browser smoke test in this package's test/integration/. The smoke test runs open → snapshot → close against https://example.com and verifies enrichment fires end-to-end.

See also

• @sightmap/playwright — sister wrapper for @playwright/cli. Same four enriched commands, different browser backend.
• @sightmap/mcp — the MCP-server alternative with the curation tool family.
• @sightmap/sightmap — the underlying matcher, lint, and validate library.