Plugin (Claude Code)

@sightmap/plugin is the Claude Code plugin for Sightmap. It composes the MCP server with six slash commands for common curation tasks, two subagents that do the work, and four advisory hooks that validate every .sightmap/ mutation as it happens.

The plugin doesn’t replace the MCP server — it leans on it. Run both together and Claude Code curates your sightmap with type safety, cascade tracking, and a tight feedback loop on every edit.

What’s in the plugin

Slash commands

Six commands for the recurring jobs. Each command delegates to a same-named skill (the procedure) which dispatches to a subagent (the worker).

Command	What it does
/sightmap:init	Initialize a new .sightmap/ corpus (skeleton only). Refuses if one already exists.
/sightmap:bootstrap	Discover views by running the dev server, capturing a fiber-tree snapshot via sightmap_runtime_snapshot, walking routes, and staging entries through the sightmap_propose_* family. Commits after review.
/sightmap:audit	Read-only audit across six defect classes — orphan views, broken selectors, missing components, route conflicts, stale memory, fixture drift.
/sightmap:fix	Propose patches for /sightmap:audit findings. Confirm-first by default; /sightmap:fix --apply opts in to auto-apply. Handles both semantic (description, memory) and structural (name, route, components) patches.
/sightmap:explain	Look up a view by name; returns a paragraph-level summary so the main thread never has to load the full view JSON.
/sightmap:reflect	Walks UI source files edited this turn that contain data-sightmap markers and proposes description/memory updates for the affected views. Use at the end of a turn that touched UI source.

Subagents

Two specialized agents. The read/write split is deliberate — the auditor literally can’t mutate files, even if it tries.

• sightmap-assistant — write-capable curator. Tools include the full MCP write surface (sightmap_add_view, sightmap_update_view, sightmap_delete_view, sightmap_init_project, the entire proposal family) plus Read, Glob, Grep, Bash. Delegated to from the init, bootstrap, explain, fix, and reflect skills.
• sightmap-auditor — read-only auditor. Tools are restricted to read-side MCP (sightmap_list_views, sightmap_get_view, sightmap_check) plus Read, Glob, Grep. No Write, Edit, or write-side MCP tools available. Delegated to from the audit skill.

The dispatch chain — slash command → skill → Task tool → subagent → MCP tools — exists so the main thread never has to load every view file: the subagent absorbs the corpus and returns only what the main thread needs.

Skills

Each slash command maps 1:1 to a skill of the same name (audit, bootstrap, explain, fix, init, reflect). The skill file holds the procedure — when to use it, what subagent to dispatch to, and how to format the response. Agents can also invoke skills directly via the Skill tool without going through the slash command.

What the hooks do

Role	Script	When
SessionStart	bin/session-start.sh	Once per session, unconditional. Loads the sightmap into context so the agent knows what’s there.
PreToolUse	bin/pre-tool-use-advisory.sh	Before Write or Edit on .sightmap/**. Nudges the agent toward sightmap_update_view instead.
PostToolUse	bin/post-tool-use-validate.sh	After Write/Edit/MultiEdit on .sightmap/**. Runs sightmap check --stdin; surfaces validation errors immediately.
Stop	bin/stop-summary.sh	Once per turn. If UI source files containing data-sightmap markers were edited, prints a one-line nudge toward /sightmap:reflect to capture description/memory updates for the affected views.

All four are advisory. They print to stderr/stdout but never block the user’s edit. Direct edits to .sightmap/ files remain valid — the hooks just add a feedback loop the bare filesystem doesn’t have.

The PostToolUse hook is the load-bearing one. When an agent (or you) writes invalid YAML, the next thing the agent sees is the diagnostic. That’s usually enough for it to self-correct on the next turn, no manual intervention required. The SessionStart, PreToolUse, and Stop hooks are quality-of-life: they reduce wasted turns by giving the agent the context to make a better first choice.

Install

In Claude Code:

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

That registers slash commands, skills, subagents, and the bundled @sightmap/mcp curation tools. Each per-harness manifest declares a compatibleMcpVersion; Claude Code reads that and pins the bundled MCP to a known-good version.

The hook scripts shell out to npx --no-install sightmap by default. Override with the SIGHTMAP_BIN environment variable if you need a pinned binary path (useful in monorepos and CI).

Local development

To work on the plugin itself, clone the standalone repo and symlink:

git clone https://github.com/sightmap/plugin
cd plugin
mkdir -p ~/.claude/plugins/sightmap
ln -sf "$(pwd)/bin"   ~/.claude/plugins/sightmap/bin
ln -sf "$(pwd)/hooks" ~/.claude/plugins/sightmap/hooks

Version pinning

@sightmap/plugin’s plugin.json declares compatibleMcpVersion — a semver range or exact version of @sightmap/mcp known to work with this plugin release. Two consumers:

1. The plugin’s own bundled MCP config uses @sightmap/mcp@<compatibleMcpVersion> so the plugin install pins what the agent runs.
2. sightmap init (manual path) reads the same field from the plugin tarball and writes the same pin into the project’s .mcp.json. The init also sets SIGHTMAP_PLUGIN_VERSION on the spawned MCP env, giving MCP a chance to soft-warn on incompatible combinations (see @sightmap/mcp).

The plugin repo’s CI keeps compatibleMcpVersion current as @sightmap/mcp releases.

Composition with @sightmap/mcp

The plugin presumes the MCP server is also configured for the host agent. Run both:

• The MCP server provides the tool surface — sightmap_update_view, sightmap_check, sightmap_list_views, etc. This is what the agent calls.
• The plugin hooks observe the agent’s tool calls and run validation around them. This is what gives the agent feedback when it bypasses MCP and edits YAML directly.

Either works alone:

• MCP only — the agent has typed curation tools but no validation feedback when it falls back to raw Write. Fine for trusted environments.
• Plugin only — every .sightmap/ edit gets validated, but the agent doesn’t have the typed tool surface, so it edits YAML by hand more often. Fine for quick experiments.
• Both — typed tools, validation feedback, the SessionStart context load. The recommended setup.

Multi-host parity

The plugin ships per-harness manifests:

• .claude-plugin/ — Claude Code
• .codex-plugin/ — Codex CLI
• .cursor-plugin/ — Cursor
• .opencode/ — OpenCode

Each manifest declares its host’s settings (skills, hooks, MCP) and a compatibleMcpVersion field for the bundled MCP. Hook scripts use a normalized stdin layer so the same logic runs across hosts. Install commands vary per host — see each host’s plugin docs for the exact phrasing of /plugin marketplace add and /plugin install.

Tip

If you’re using Claude Code and you’ve already wired up @sightmap/mcp, installing the plugin is a 30-second improvement with no real downside. Try it.