Skip to content
Sightmap

Authoring

You don’t author a sightmap by hand.

A sightmap describes how a web app behaves at runtime — its routes, components, network calls, and the institutional knowledge an agent needs to drive it. .sightmap/ is curated authority, not a generated artifact: the agent observes the running app, proposes the YAML, and commits it. The tools in this section are the curation surface.

The mental model

Section titled “The mental model”

Curation runs in two phases:

  1. Bootstrap — once, when you first add Sightmap to a repo. sightmap init scaffolds an empty .sightmap/app.yaml, wraps your app entry with <SightmapProvider>, and wires the MCP server into your agent harness. You add the Vite plugin, start your dev server, and an agent walks the running app: it fetches the live fiber-tree, proposes views and components with ranked selectors, and commits the batch to .sightmap/.
  2. Maintain — every time routes change, components move, or the agent learns something new about the app, you re-run the bootstrap loop or call the curation tools directly. Existing fields (memory, requests, manual selector overrides) are preserved.

The agent owns the entire corpus. There is no source-side codegen; static drift detection was removed in v0.6. Reconciliation is agent-driven, against the runtime.

What writes what

Section titled “What writes what”

Different surfaces handle different parts of the loop:

  • sightmap init (@sightmap/sightmap) scaffolds the empty corpus, codemods the provider, and wires the agent harness. One-shot, idempotent.
  • The React runtime (@sightmap/react) exposes the live fiber-tree at /__sightmap__/snapshot.json. It never writes to .sightmap/.
  • An agent (via the MCP server, the Claude Code plugin, or any host) writes the corpus — proposing from the runtime snapshot, committing accepted proposals, patching fields directly with sightmap_update_view.
  • You rarely touch YAML directly. When you do, sightmap check validates the corpus against itself — schema, key ordering, cross-file refs, duplicates.

Pages in this section

Section titled “Pages in this section”
  • @sightmap/react — the React runtime. Mount the provider, add the Vite plugin, and an agent bootstraps .sightmap/ against the running app.
  • @sightmap/cli — the sightmap command-line tool. validate, lint, match, explain. Used in CI and during day-to-day curation.
  • @sightmap/core — the library API behind the CLI. For tool builders integrating sightmap into IDEs, MCP servers, or custom workflows.
  • @sightmap/mcp — an MCP server combining browser introspection with .sightmap/ curation tools. The recommended way to let a host agent author for you.
  • @sightmap/playwright — sightmap-aware wrapper around @playwright/cli. Same enriched snapshots as @sightmap/mcp over a shell-invocation surface — the no-MCP path.
  • @sightmap/agent-browser — sister wrapper for Vercel’s agent-browser CLI. Same four enriched commands; passes through -p <provider> for hosted Chrome (Browserless, Browserbase, Kernel, …).
  • Plugin (Claude Code) — advisory hooks that nudge Claude Code toward MCP curation tools and validate every .sightmap/ mutation.

If you’re starting from scratch, follow the quickstart — it walks the bootstrap-and-maintain loop end to end.