repomap

A stable context layer for your codebase. One file. Maximum LLM cache hits.

npx repomap-llm init

That single command generates a REPOMAP.md at your repo root, installs a post-commit hook that keeps it fresh, and gives every LLM you use a permanent, cache-friendly context prefix for your codebase.

Why this exists

Every time you ask Claude / Cursor / Copilot for help, the model re-reads your repo from scratch. Context tokens get billed. Latency adds up. The same files get scanned hundreds of times per week.

repomap-llm writes one structured markdown file that describes your project — overview, tech, architecture, modules, dependencies, co-changes, recent activity — and orders sections from most stable → most volatile.

Drop it at the start of every system prompt. The inference engine's KV cache fires after the first call. Every subsequent request reuses the prefix.

Result: ~90% cost reduction and ~80% latency reduction on repeated calls in the same repo.

How it works

┌─────────────────────────────────────────────────┐
│  REPOMAP.md  (stable → volatile, top to bottom) │
├─────────────────────────────────────────────────┤
│  ## overview        ◄── cached forever          │
│  ## tech            ◄── cached across commits   │
│  ## architecture    ◄── cached across commits   │
│  ## patterns        ◄── cached across commits   │
│  ## modules         ◄── changes occasionally    │
│  ## dependencies    ◄── changes occasionally    │
│  ## co-changes      ◄── changes per commit      │
│  ## hot-zones       ◄── changes per commit      │
│  ## recent          ◄── changes per commit      │
└─────────────────────────────────────────────────┘
        │
        └─► When you commit, only the suffix changes.
            The KV cache stays warm across requests.

A post-commit git hook regenerates the file in the background after each commit. Zero manual upkeep.

Commands

| command | what it does | |---|---| | npx repomap-llm init | First-time setup. Generates the file + installs the post-commit hook. | | npx repomap-llm | Regenerate REPOMAP.md (default command). | | npx repomap-llm watch | Auto-regenerate on file changes (debounced 800ms). | | npx repomap-llm status | Show health: file age, token count, hook status. |

What the output looks like

---
repomap: 1.0
generated: 2026-04-26T08:13:59Z
repo: vraj00222/repomap
files: 17
tokens: ~1131
---

## overview
A stable context layer for your codebase. Built with TypeScript.
Contains 17 source files across the tracked directories.

## tech
- language: TypeScript
- framework: Next.js
- package_manager: npm
- test_runner: vitest
- node_version: >=18

## architecture
- `src/` — application source code
- `tests/` — test suites

## patterns
- file_naming: kebab-case
- module_style: ESM TypeScript

## modules
| path | exports | purpose | stability |
|---|---|---|---|
| `src/cli.ts` | `main` | CLI entry point | 5 |
| `src/analyzer/index.ts` | `analyzeRepo` | Walk the repo and parse files | 3 |
...

## dependencies
- `src/cli.ts` → `src/commands/init.ts`, `src/commands/generate.ts`
- `src/commands/init.ts` → `src/hooks/install.ts`

## co-changes
- `src/auth/login.ts` ↔ `src/auth/session.ts` (12 commits together)

## hot-zones
- `src/api/handler.ts` (8 commits)

## recent
| hash | author | message | files |
|---|---|---|---|
| abc1234 | jane | fix login redirect | 3 |

Works with

Configuration

Drop a repomap.config.json at your repo root, or add a repomap field to your package.json. Every option has a sensible default — only set what you want to override.

{
  "include": ["src/**", "app/**", "lib/**"],
  "exclude": ["**/*.test.*", "**/node_modules/**"],
  "maxTokens": 8000,
  "maxFiles": 500,
  "stableThreshold": 2,
  "output": "REPOMAP.md",
  "languages": [],
  "coChangeLookback": 90,
  "commitFlag": false
}

| option | default | description | |---|---|---| | include | ["src/**","app/**","lib/**","pages/**"] | Globs of files to analyze | | exclude | sensible defaults | Globs to skip (always skips node_modules, dist, build, .next, __pycache__) | | maxTokens | 8000 | Token budget — volatile sections are dropped first when exceeded | | maxFiles | 500 | Hard cap on files analyzed (prevents runaway on monorepos) | | stableThreshold | 2 | Files with fewer commits in the lookback window count as "stable" | | output | REPOMAP.md | Output filename | | languages | auto | Subset of ["ts","js","py","go","rs"]; empty = auto-detect | | coChangeLookback | 90 | Days of git history used for the co-change graph and hot-zones | | commitFlag | false | If true, REPOMAP.md is committed (not gitignored) |

Install

# recommended
npx repomap-llm init

# global
npm install -g repomap-llm

# project-local
npm install --save-dev repomap-llm

Requires Node ≥ 18. Works on macOS, Linux, and Windows.

FAQ

Contributing

PRs welcome. The codebase is small and well-tested.

git clone https://github.com/vraj00222/repomap
cd repomap
npm install
npm test

License

MIT © vraj