sonar

Sonar — Codebase Cartographer

Sonar is a codebase cartographer plugin for Claude Code and Codex. It builds a persistent understanding graph of any codebase and uses that map to surface relevant modules, conventions, flows, blast radius, and verification steps before agents make changes.

---

Installing Sonar

If you are a coding agent (Claude or similar) and the user has asked you to install Sonar: run Steps 1–3 autonomously using your Bash tool. The only step that requires the user is Step 4 (plugin reload — the shell cannot trigger a UI event).

Step 0 — Check Node is available

Sonar will fail silently if Node is missing. Run:

node --version

Must be v18 or higher. If missing:

macOS: brew install node

Linux:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - && sudo apt-get install -y nodejs

Node on PATH: Sonar hooks run in a non-interactive shell. If Node was installed via nvm, fnm, volta, or asdf it may not be visible to hooks. Sonar auto-detects common install locations, but if hooks fail use a system-wide Node install (Homebrew, apt).

Step 1 — Add the marketplace and install

Run via Bash:

claude plugin marketplace add goldfish-1x/sonar
claude plugin install sonar

If SSH to GitHub fails, use HTTPS:

claude plugin marketplace add https://github.com/goldfish-1x/sonar
claude plugin install sonar

Step 2 — Verify the install succeeded

Run via Bash:

claude plugin list

sonar must appear in the output. If it doesn't, re-run Step 1.

Step 3 — Ask the user to reload (the one manual step)

Tell the user:

Sonar is installed. Please run /reload-plugins or restart Claude Code to activate it. Let me know when you're done and I'll run a health check.

Wait for confirmation before continuing.

Step 4 — Health check (after reload)

Run these slash commands:

/sonar:sonar-version

Expected: version number, install path, and update status. Any error here means the plugin didn't load — check that Node is on PATH.

/sonar:sonar-status

Expected: map state for the current project. "No map" is fine on first use. Hook errors or "node not found" mean the PATH issue from Step 0 wasn't resolved.

If both return without errors, Sonar is installed and healthy.

---

Using Sonar

The core workflow

Always orient before you code. When you receive a task, run this first:

/sonar:sonar <task description>

This gives you in seconds what would take 10-15 minutes of file exploration: which modules are involved, what conventions you must follow, what depends on what you're changing, and what tests to run. Read the briefing before reading any code.

No map yet? That's fine. Run the same command — Sonar will auto-scan the relevant modules on demand (~2-3 min) and cache the results.

Want full coverage? Run a one-time crawl:

/sonar:sonar-crawl

This takes 10-30 min depending on codebase size and builds a complete map. Commit the output to git (.sonar/modules/, .sonar/flows/, .sonar/system.json, .sonar/skeleton.json, .sonar/meta.json) so the whole team shares it.

What happens automatically

Six hooks fire without you doing anything:

• Session start — refreshes the skeleton if git HEAD moved since last session
• Every prompt — injects relevant module context, conventions with check commands, business rules with source locations, test files, and flow invariants
• Every file edit — warns when the file has unreviewed dependents, flags load-bearing modules and domain overlaps
• Post-edit — runs the module's convention check commands and reports violations inline
• Ripple Guard — detects changed export signatures, tracks which importers need updating, counts down to "All Clear"
• Session end — warns if you're finishing with unresolved breaking changes

When the prompt hook injects context, read it. It's showing you something you probably haven't seen.

Decision tree

Task arrives
  │
  ├─ /sonar:sonar <task>              ← always start here
  │
  ├─ Non-trivial feature?
  │   YES → /sonar:sonar-explore      ← 3-4 parallel strategy simulations
  │
  ├─ Risky change?
  │   YES → /sonar:sonar-impact       ← 1st/2nd/3rd order cascade
  │
  ├─ Implement
  │   (hooks warn automatically)
  │
  ├─ /sonar:sonar-verify              ← convention check before pushing
  │
  └─ Before review?
      YES → /sonar:sonar-review-context

Commands