codemap-index

Auto-generate .codemap/ index files for AI coding tools. Maps features to files, endpoints, and flows — zero config.

Built to help AI assistants (Claude Code, Cursor, Copilot) navigate your codebase efficiently by reading a small index file instead of scanning hundreds of files.

Install

npm install -g codemap-index

Usage

Run from your project root:

# Auto-discover features and generate .codemap/ files
codemap generate

# Check for stale file references
codemap validate

How it works

1. Scans backend/controllers/ — each controller becomes a feature
2. Auto-groups controllers by prefix (SupplierController + SupplierActivityController → supplier)
3. Traces backend dependencies via constructor injection (controllers → services → models)
4. Matches frontend files by keyword (pages, services, components, store)
5. Extracts API endpoints from controller route attributes
6. Preserves manually written flow descriptions across regenerations

Output

Each feature gets a .codemap/{feature}.json file:

{
  "feature": "trial",
  "description": "trial (1 controller(s), 7 files)",
  "key_files": [
    "backend/controllers/TrialController.cs",
    "backend/services/TrialService.cs",
    "backend/Models/User.cs",
    "frontend/src/services/trialService.js"
  ],
  "endpoints": [
    "POST /api/trial/claim",
    "GET /api/trial/eligibility"
  ]
}

Merge groups

Create .codemap/groups.json to merge related features:

{
  "billing": ["subscription", "membership", "invoice"]
}

This combines all files and endpoints from subscription, membership, and invoice into a single billing.json codemap.

Why use this?

| Without codemap | With codemap | |----------------|-------------| | AI scans 50+ files to find relevant code | AI reads 1 JSON file (~20 lines) | | ~10,000 tokens per question | ~5,000 tokens per question | | Slow, expensive, often misses files | Fast, cheap, complete coverage |

Supported stacks

Currently optimized for:

• Backend: .NET / ASP.NET Core (controllers, services, models)
• Frontend: React / Vite (pages, services, components, store)

The architecture is extensible — PRs welcome for other frameworks.

Programmatic API

const { generateCodemaps, resolveFiles, traceImportChain } = require('codemap-index');
const { autoDiscover, generateAutoCodemaps } = require('codemap-index/src/auto-discover');

// Auto-discover and generate
generateAutoCodemaps('/path/to/project', '.codemap');

// Or use individual functions
const files = resolveFiles(['backend/controllers/Trial*'], rootDir);
const allFiles = traceImportChain(files, rootDir, 3);

License

MIT