Plugin (Claude Code)

@sightmap/plugin is the Claude Code plugin for Sightmap. It composes the MCP server with three advisory hooks that nudge the agent toward typed curation tools and 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 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 `mcp__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.

All three 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 and PreToolUse hooks are quality-of-life: they reduce wasted turns by giving the agent the context to make a better first choice.

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 enable it in ~/.claude/settings.json:

{
  "enabledPlugins": ["sightmap"]
}

A one-command marketplace install lands in the next plugin release. Check @sightmap/plugin on npm for the current path.

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

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.

Cursor and Codex parity

Currently Claude Code only. The hook scripts use a normalized stdin layer so the same logic can run across hosts; ports for Cursor and Codex are tracked in the plugin repo. Until then, those hosts can run the MCP server directly — they get the typed tools, just not the hook-driven feedback loop.