repomap

Give your AI coding agent a 3k-token map of any codebase in under a second — so it stops re-reading the entire repo every session.

repomap is an MCP server, CLI, and Claude Code plugin (skill + slash commands + optional SessionStart hook) that generates a compact, cached architectural map of any repository: module boundaries, entry points, internal dependency graph, cycle detection, key symbols per file, and "hot files" ranked by fan-in + recent git churn.

100% local. Zero network calls. Incremental SHA-256 caching.

Before vs. After (Real Benchmarks)

Measured on real open-source repositories using mcp-repomap v0.1.0 (default 3500 token budget):

Instead of burning ~300k+ tokens and minutes of grep/file-reads on every new session, your agent reads a ~3.4k-token map in <0.5s and opens only the exact files it needs.

Related MCP server: Weavatrix

Demo

You can re-record this demo GIF anytime using VHS:

vhs demo.tape

Quick Install

Option 1: Claude Code Plugin (MCP + Skill + Slash Commands + Auto-Refresh Hook)

Inside Claude Code:

/plugin marketplace add rohanpandityy35-bit/repomap
/plugin install repomap@repomap

This installs:

• MCP server (mcp-repomap)

• Skill (skills/repomap/SKILL.md) teaching Claude to read the map before broad exploration or refactors

• Slash commands: /repomap:map, /repomap:impact <file>, /repomap:refresh

• SessionStart hook: silently refreshes .repomap/ if stale (>24h or git HEAD changed)

Option 2: MCP Server Only

claude mcp add repomap -- npx -y mcp-repomap

Option 3: CLI (No MCP Required)

npx -y --package=mcp-repomap repomap generate .
# or install globally:
npm install -g mcp-repomap
repomap overview .

Usage Examples

MCP Tools

CLI Commands

# Generate compact Markdown map (default ~3,500 tokens) and cache in .repomap/
repomap generate . --budget 3000

# Export as Mermaid dependency graph or JSON
repomap generate . --format mermaid
repomap generate . --format json

# Quick architecture + entry points overview
repomap overview .

# Find symbols or files matching a query
repomap find Calculator .

# Inspect incoming/outgoing dependencies (depth 2)
repomap deps src/core/graph.ts . --direction both --depth 2

# Check blast radius before editing a shared file
repomap impact src/core/types.ts .

Supported Languages

How It Works

1. Scan: Walks the repo respecting .gitignore (root and nested), skipping node_modules, dist, build, lockfiles, binaries, and files >1MB.

2. Parse & Cache: Computes SHA-256 per file and parses only changed files via web-tree-sitter WASM grammars. Stores cache in .repomap/map.json and .repomap/REPOMAP.md.

3. Graph & Rank: Resolves internal imports, detects dependency cycles, computes fan-in/fan-out, extracts entry points (package.json, pyproject.toml, main.go, src/main.rs, Dockerfile, CI workflows), and ranks hot files by fan-in + 90-day git log churn.

4. Budgeted Output: Emits architecture + entry points + hot files first, then fills remaining token budget with key symbols ordered by file importance.

Roadmap

• Monorepo workspace awareness (pnpm/npm workspaces, Cargo workspaces, Go multi-module)

• Language-specific path alias resolution (tsconfig.json paths, Python PYTHONPATH)

• Tree-sitter WASM support for C/C++, Ruby, C#, and Kotlin

• Watch mode (repomap watch) for live .repomap/ updates during development

FAQ

Does repomap send my code anywhere? No. Everything runs 100% locally on your machine with zero network calls.

Should I commit .repomap/ to git? Usually no — add .repomap/ to your .gitignore (repomap will remind you if it's not ignored).

Why is the npm package named mcp-repomap? repomap-mcp was already taken on npm, so we published under mcp-repomap (which exposes both mcp-repomap and repomap binaries).

License

MIT