system-map

Architecture-context CLI for TypeScript repos (Next.js / SvelteKit / Vite-React). Answers specific structural questions deterministically — blast radius, state ownership, coupling, leaf nodes, missing error surfaces — so humans and AI coding agents stop spelunking through files to understand what a change will touch.

Status: 0.1 — usable, API may shift. Feedback issues welcome.

Install

npm install -g system-map
# or run without installing:
npx system-map init

Quickstart

cd your-typescript-repo
system-map init             # writes .system-map/ (gitignore'able)
system-map review           # what's worth looking at right now
system-map ask "blast radius of Cart"
system-map why useCartStore # depth view on one subject
system-map insights         # ranked structural signals

init is safe — it only writes inside .system-map/ and (opt-in) generates a domain glossary stub at .system-map/domain.md.

What it answers

• Blast radius — "if I change X, what else breaks?"
• State ownership — who owns the state a module depends on; flags when two stores claim the same slice.
• Coupling — pairs of modules that always change together.
• Missing error surfaces — routes/services that swallow errors with no logger, boundary, or thrown propagation.
• Leaf nodes — files nothing imports (dead code candidates or entry points the parser missed).

All answers come from a deterministic extractor (no LLM in the data path). An optional LLM step proposes domain names for human approval — never silently asserts.

Using with Claude Code

system-map ships with a skill/ directory. To wire it into Claude Code:

# from the cloned/installed package, copy the skill:
cp -r node_modules/system-map/skill ~/.claude/skills/system-map

Claude Code will then call system-map ask / system-map review when the question shape fits. Add a one-line pointer to your project's CLAUDE.md for other agents:

For architecture questions, run `system-map ask "<question>"` or `system-map review`.

CLI reference

All commands run against the current working directory. Pass --cwd <path> to target another directory.

system-map init                            # extract + write .system-map/
system-map refresh                         # re-extract after changes
system-map review                          # ranked findings worth acting on
system-map ask "what owns auth state?"
system-map why useCartStore                # depth view on one subject
system-map insights                        # all structural signals
system-map insights --surface api/checkout # scope to one server surface
system-map brief                           # write CLAUDE.md-shaped brief
system-map view --open                     # interactive HTML viewer
system-map install-hooks                   # optional: pre-edit hook for Claude Code

JSON output is available on ask, why, insights, and review via --json.

Supported frameworks

• Next.js (app router)
• SvelteKit (initial — feedback welcome)
• Vite + React Router (initial — feedback welcome)

TypeScript only. Cross-repo / multi-service mapping is out of scope (this is per-repo).

Feedback

Open an issue at github.com/tylernigrofr/system-map/issues. Particularly useful:

• Repos where system-map review surfaces nothing interesting (false negatives).
• Repos where it surfaces noise (false positives).
• Questions you asked an agent that it should have routed to system-map ask but didn't.

License

MIT