codemap

Codemap — Universal Codebase Map Generator

A Claude Code plugin that generates CODEBASE_MAP.md — a structural index of any codebase designed for LLM navigation during agentic coding sessions.

What It Does

Produces a dependency-aware map of your codebase with:

• Dependency graph (inbound + outbound) per file — assess blast radius before changes
• Public interface signatures — know what each file exposes
• Side effect warnings — lifecycle hooks, event listeners, global mutations
• Git intelligence — churn, fix rates, ownership, co-change coupling, code notes
• Human annotations — curated descriptions, gotchas, domain notes (preserved across regenerations)

Two-Layer Architecture

• Layer A (auto-generated): Static analysis extracts file paths, exports, imports, signatures, side effects. Disposable and reproducible.
• Layer B (human annotations): Stored in CODEBASE_MAP.annotations.yml. Preserved across regenerations. Removed files have annotations archived to orphaned section.

Git Intelligence

When run in a git repository, the plugin extracts behavioral signals from commit history that static analysis cannot see:

Signal	What It Detects	Why It Matters
Churn	Files with high commit frequency (top 10%)	High-churn files are actively developed or chronically broken — be cautious
Fix Frequency	Files where >30% of commits are bug fixes	Empirically fragile code — "here be dragons"
Co-Change Coupling	File pairs that frequently change together (>60% ratio)	Hidden dependencies not visible in imports — critical for blast radius
Ownership	Files where one author has >80% of commits	Bus factor risk — patterns may be idiosyncratic and undocumented
Recency	Last modification date (active/stable/dormant)	Dormant files are either rock-solid or abandoned — adjust confidence
Reverts	Files involved in 2+ reverted commits	Stronger signal than fix frequency — the fix itself failed
Code Notes	TODO, FIXME, HACK, WORKAROUND markers	Developer breadcrumbs — informal risk markers already in the code

How It Works

The git intelligence module (scripts/git-intel.sh) runs as part of the map generation pipeline:

1. Collect: Single git log pass extracts commits, authors, messages, and file changes into cacheable TSV files
2. Analyze: Seven parallel sub-scripts compute churn, fixes, ownership, recency, reverts, co-changes, and code notes
3. Flag: Configurable thresholds determine which files get flagged (high churn, bug prone, single owner, etc.)
4. Output: Produces both machine-readable JSON (CODEBASE_GIT_INTEL.json) and human-readable Markdown summary, plus intermediate tags injected into the codebase map

Output Files

• .codemap/CODEBASE_GIT_INTEL.json — Full per-file intelligence data with flags
• .codemap/CODEBASE_GIT_INTEL.md — Summary report: high-churn files, coupled pairs, single-owner files, code notes
• CODEBASE_MAP.md — Git intel rendered inline on each file entry (only when flags are present)

Map Entry Example

Files with noteworthy git signals get a compact **Git:** line:

### `src/services/payment_gateway.rb`
**Exports:** `PaymentGateway`

**Dependencies:**
- → `internal:services/order_service` (uses: create_order)

**Side Effects:**
- `after_commit` triggers `WebhookDispatcher`

**Git:** 🔥 47 commits · 🐛 25% fixes · 👤 sarah(89%)
- 🔗 `tax_calculator.rb`(66%), `pricing_engine.rb`(60%)
- 📝 FIXME:84 race condition under concurrent charges

Configuration

Thresholds are configurable via .codemaprc.yml in the project root:

git_intel:
  churn_window_days: 90
  cochange_window_days: 180
  dormant_threshold_days: 180
  high_churn_percentile: 90
  bug_prone_fix_ratio: 0.30
  single_owner_threshold: 0.80
  tight_coupling_ratio: 0.60
  cochange_min_occurrences: 3
  skip_bulk_commit_threshold: 50

All values have sensible defaults — zero config required.

Edge Cases Handled

• Not a git repo: Git intelligence is silently skipped
• Shallow clones: Warning emitted, analysis runs on available history
• < 30 commits: Skipped entirely — insufficient data for meaningful behavioral analysis
• Bulk commits (>50 files): Excluded from co-change analysis to avoid noise from refactors/migrations
• Merge commits: Excluded by default (--no-merges) to avoid inflated metrics

Supported Languages