codebase-map

A Claude Code plugin that installs a persistent, hand-curated project map (codebase-map.json) plus auto-update hooks. Claude reads the map before grep/explore — saves tokens, encodes landmines, keeps architecture visible across sessions.

One slash command. One JSON file. Three hooks. Your codebase, navigable.

Install

# In Claude Code:
/plugin marketplace add DIV7NE/codebase-map
/plugin install codebase-map@codebase-map

Then in any project:

/codebase-map

That's it. Auto-detects state and installs or refreshes.

What /codebase-map does

In the project where you invoke it:

File written	Purpose
codebase-map.json	Source of truth — routes, schema, lib symbols, components, user journeys, recipes, landmines
codebase-map.html	Browser viewer (renders JSON + Mermaid diagrams via CDN)
.claude/settings.json	Wires 3 hooks (merges if file already exists)
.claude/hooks/codebase-map-watcher.mjs	PostToolUse — reminds Claude to update map when structural files change
.claude/hooks/codebase-map-stop.mjs	Stop — turn-end nag if map is stale
.claude/hooks/codebase-map-session-start.mjs	SessionStart — surfaces map status
.claude/hooks/codebase-map-patterns.mjs	Project-specific watched globs (auto-generated from stack detection)
CLAUDE.md directive	Forces Claude to consult map before grep/explore
.gitignore	Adds /.claude/.cache/
.githooks/pre-push	Git pre-push hook — blocks git push if codebase-map.json is dirty. Enforces atomic code+map commits. Skip with --no-git-hook.

Usage

/codebase-map                # auto: install if missing, refresh if present
/codebase-map --check        # report state, no writes
/codebase-map --force        # overwrite existing map
/codebase-map --refresh-only # regen JSON only, skip hooks/CLAUDE.md/git hook
/codebase-map --no-git-hook  # install everything except git pre-push hook

Idempotent. Safe to re-run. Asks before overwriting an existing codebase-map.json unless --force.

View the map

py -m http.server 8765
# or: npx serve .
# then open http://localhost:8765/codebase-map.html

The HTML viewer renders all sections including Mermaid diagrams. The JSON is canonical — the HTML auto-derives.

Stack detection

Auto-picks watched globs based on what it finds at project root:

Detected	Watches
Next.js App Router	src/app/api/**/route.ts, src/app/**/page.tsx, lib/**, schema files
Vite + React	src/routes/**, src/lib/**, src/components/**
SvelteKit	src/routes/**/+page.svelte, src/routes/**/+server.ts, src/lib/**
FastAPI / Django	app/api/**/*.py, app/models/**/*.py, migrations
Express	src/routes/**, src/controllers/**, src/models/**
Generic	src/**, lib/**, root configs

Override by editing .claude/hooks/codebase-map-patterns.mjs after install.

Why hand-curated, not auto-generated?

Auto-extractors (graphify, ts-morph, tree-sitter) produce noisy graphs with thousands of nodes. The codebase-map is intentionally lossy: only the ~200 lines worth knowing about. Everything else is one Grep away.

Lives in the map:

• Intent, user journeys, landmines, recipes (things Claude can't derive from code alone)
• Route inventory, DB schema summary (tedious to re-derive every session)
• Architectural decisions (change rarely)

Does NOT live in the map:

• Per-function call graphs (let AST tools do that on demand)
• Anything that decays faster than humans can maintain

Maintenance loop

You edit a structural file
  → PostToolUse hook fires
  → Claude sees 🗺️ reminder with section to update
  → Claude updates codebase-map.json before ending turn
  → Map stays current

When the map drifts, Stop hook nags at turn end. SessionStart hook surfaces map age. Map is committed to git — full audit trail of architecture evolution.

Structure

codebase-map/                                       # marketplace root
├── .claude-plugin/marketplace.json
└── codebase-map/                                   # the plugin
    ├── .claude-plugin/plugin.json
    ├── commands/codebase-map.toml                  # /codebase-map slash command
    ├── skills/codebase-map-setup/                  # bundled installer skill
    │   ├── SKILL.md                                # full install procedure
    │   └── templates/
    │       ├── codebase-map.html                   # HTML viewer
    │       ├── settings.json                       # hook wiring
    │       ├── claude-md-snippet.md                # CLAUDE.md directive
    │       └── hooks/
    │           ├── codebase-map-watcher.mjs        # PostToolUse
    │           ├── codebase-map-stop.mjs           # Stop
    │           ├── codebase-map-session-start.mjs  # SessionStart
    │           └── codebase-map-patterns.example.mjs
    └── README.md

Development / contributing

git clone https://github.com/DIV7NE/codebase-map
cd codebase-map

# Install locally for testing:
cp -r . ~/.claude/plugins/marketplaces/codebase-map/
# then in Claude Code: /plugin reload

PRs welcome. Especially: more stack detection patterns, viewer improvements, better landmine encoding.

License

MIT — see LICENSE.