Quickstart (agent-authored)

The recommended path for any app that isn’t React Router 7. You install one tool; an agent does the rest.

You don’t write .sightmap/ YAML by hand. The format is designed to be machine-curated against a running app — the agent inspects what’s actually rendered, names what matters, and writes the file. You review and commit.

Pick a tool

Tool	When to use it
Claude Code plugin (@sightmap/plugin)	You use Claude Code. Simplest path — install, restart, ask.
MCP server (@sightmap/mcp)	Any other agent that speaks MCP (Cursor, Windsurf, Codex, custom).

Both wrap the same underlying curation tools. The plugin is just a thin Claude Code adapter.

Path A — Claude Code plugin

1. Install

For local development, symlink the plugin into Claude Code’s plugin directory:

mkdir -p ~/.claude/plugins/sightmap
ln -sf "$(pwd)/bin"   ~/.claude/plugins/sightmap/bin
ln -sf "$(pwd)/hooks" ~/.claude/plugins/sightmap/hooks

Then add sightmap to your ~/.claude/settings.json enabledPlugins. A one-command marketplace installer ships in WI-3.

2. Ask Claude to bootstrap

In your project root, ask Claude Code:

Bootstrap a .sightmap/ for this app.

The plugin’s hooks load the spec into the session and validate every write. Claude drives the running app, names views and components, and writes YAML.

3. Review and commit

Open the generated files. Check the names match what your team would call those screens. Commit.

→ Authoring with the plugin

Path B — MCP server

1. Install and run

pnpm add -D @sightmap/mcp
sightmap-mcp \
  --sightmap-dir ./.sightmap \
  --curate-root ./.sightmap \
  -- npx -y @playwright/mcp@latest

The server wraps @playwright/mcp and adds sightmap-aware browser tools (sightmap_match, sightmap_snapshot, sightmap_act, sightmap_network_requests) plus a curation toolset (sightmap_list_views, sightmap_get_view, sightmap_update_view, sightmap_check, sightmap_init_project).

2. Connect your agent

Wire the MCP server into your agent’s config. Then ask the agent to call sightmap_init_project and start curating. The server handles browser introspection; your agent picks names and writes memory.

3. Review and commit

Same as path A — read what was written, sanity-check the names, commit.

→ Authoring with @sightmap/mcp

What the agent owns vs what you own

Note

Component, route, and selector edits are not exposed via MCP — those are codegen-owned territory in the React adapter, and hand-authored territory elsewhere. The MCP write tools cover only the agent-authored fields: description, intent, memory. See Curator vs consumer for the full split.

Next

• Authoring overview — the curation toolchain end to end.
• Schema reference — what valid YAML looks like.
• Memory — the field that makes a sightmap pay for itself.