Skip to content
Sightmap

Quickstart

One curation flow. The agent drives your live app and writes .sightmap/ against what it observes. Works for any web app — React + Vite gets a zero-config endpoint; anything else (Next.js, Vue, Svelte, server-rendered, hosted) uses a browser-mode snapshot through @playwright/mcp.

You don’t write the YAML by hand.

Pick your agent host

Section titled “Pick your agent host”

You’ll wire Sightmap into an MCP-capable agent. Any of these work:

HostWhen to use it
Claude Code plugin (@sightmap/plugin)You use Claude Code. Simplest path — install, restart, ask. Ships slash commands, skills, and curation hooks.
MCP server (@sightmap/mcp)Any other agent that speaks MCP (Cursor, Windsurf, Codex, OpenCode, custom).
Playwright wrapper (@sightmap/playwright)CLI-driven agents or scripts that prefer shell invocation over MCP. Same enriched commands as the MCP server.
agent-browser wrapper (@sightmap/agent-browser)CLI-driven agents that prefer Vercel’s agent-browser. Passes through -p <provider> for hosted Chrome (Browserless, Browserbase, Kernel, …).

The plugin and the MCP server share the same curation tool family — @sightmap/plugin is a thin Claude Code wrapper around @sightmap/mcp. The Playwright and agent-browser wrappers cover the browser-side primitives over a shell-invocation surface; see @sightmap/playwright and @sightmap/agent-browser for the trade-offs.

The five steps below cover the MCP path. If you’re using the plugin, install it first (one line) and skip ahead to step 5 — the rest is wrapped for you.

1. Install

Section titled “1. Install”
Terminal window
pnpm add -D @sightmap/sightmap @sightmap/mcp

If your app is React, also install the runtime:

Terminal window
pnpm add @sightmap/react

If you’re using Claude Code, that’s also when you install the plugin:

/plugin marketplace add sightmap/plugin
/plugin install sightmap@sightmap

The plugin bundles @sightmap/mcp and pins a known-good version. With the plugin installed, you can skip steps 2 and 4 below — just run /sightmap:init and /sightmap:bootstrap.

2. sightmap init

Section titled “2. sightmap init”
Terminal window
npx @sightmap/sightmap init

init detects your framework, scaffolds an empty .sightmap/app.yaml, and wires the MCP server into your agent harness (.mcp.json for Claude Code; ~/.codex/config.toml for Codex; .cursor/mcp.json; opencode.json). For React apps, it also wraps your app entry with <SightmapProvider> via codemod (with a confirmation diff).

If init can’t safely locate or rewrite your entry, it prints a snippet for you to drop in by hand.

3. Connect the runtime

Section titled “3. Connect the runtime”

How the agent captures your live app depends on your stack.

React + Vite — add the Vite plugin (zero-config endpoint mode)

Section titled “React + Vite — add the Vite plugin (zero-config endpoint mode)”
vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { sightmap } from "@sightmap/react/vite";


export default defineConfig({
  plugins: [react(), sightmap()],
});

The plugin serves two endpoints in dev:

  • /__sightmap__/sightmap.json — the merged corpus loaded by <SightmapProvider>.
  • /__sightmap__/snapshot.json — the live fiber-tree snapshot the agent will fetch via sightmap_runtime_snapshot { kind: "endpoint" }.

Anything else — browser mode (no extra setup)

Section titled “Anything else — browser mode (no extra setup)”

For non-Vite React, non-React apps, or any case where you can’t run the Vite plugin, the agent uses sightmap_runtime_snapshot { kind: "browser" } — which drives @playwright/mcp and pre-navigate-injects a bippy hook into the page. Nothing for you to install or configure beyond starting your app. Requires @playwright/mcp >= 0.0.75, which sightmap init pins for you.

4. Start your app

Section titled “4. Start your app”
Terminal window
pnpm dev

Or however you run it. The agent needs a reachable URL — local dev, a preview deploy, or a hosted Chrome (via the agent-browser wrapper) all work.

5. Bootstrap with an agent

Section titled “5. Bootstrap with an agent”

With the Claude Code plugin — run:

/sightmap:bootstrap

The skill drives the runtime snapshot, walks routes, proposes views and components, and commits the accepted batch via sightmap_commit_proposals.

Without the plugin — prompt your agent directly:

Use the sightmap MCP tools to bootstrap a sightmap of this app from the running dev server.

Either way, the agent runs the same four-call loop:

  1. sightmap_runtime_snapshot — at each route in your app.
  2. sightmap_propose_view + sightmap_propose_component — selectors ranked from stable (data-sightmap, data-testid) to fragile (ARIA, semantic tags, ids).
  3. sightmap_review_proposals — surface the staged batch for triage.
  4. sightmap_commit_proposals — write the accepted batch to .sightmap/.

Result:

.sightmap/
  app.yaml             # global routes, top-level memory
  flight-search.yaml   # one per top-level route
  account.yaml
  shared.yaml          # cross-route components

Iterate

Section titled “Iterate”

For selector stability, add data-sightmap="ComponentName" to JSX where the runtime can’t infer a stable one. The fiber walker ranks data-sightmap highest, so a marker always wins:

<button data-sightmap="LoginButton" onClick={signIn}>Sign in</button>

When source changes — new route, new component, renamed selector — re-run the bootstrap loop. Existing entries (memory, manual selector overrides) are preserved; new ones surface as proposals. With the plugin, /sightmap:reflect nudges you at the end of any turn that edited UI source containing data-sightmap markers.

For corpus-level checks, run sightmap check — schema, key ordering, cross-file references, duplicates. It validates .sightmap/ against itself; there is no static source-vs-yaml drift check (by design — .sightmap/ is curated, not generated).

Next

Section titled “Next”