repo-mapper

Generate token-budgeted maps of code repositories for LLM context. Uses tree-sitter for accurate parsing and PageRank for importance ranking.

Features

• Token budgeting: Fit the most important code into your context window
• Smart ranking: PageRank algorithm prioritizes frequently-referenced code
• Module clustering: Groups files by directory with global top-50 guarantee
• Focus mode: Bias output toward files you're working on
• Fast caching: Only re-parses changed files

Supported Languages

| Language | Extensions | |----------|------------| | TypeScript | .ts, .tsx, .mts, .cts | | JavaScript | .js, .jsx, .mjs, .cjs | | Python | .py, .pyw | | Go | .go | | Rust | .rs | | Solidity | .sol |

Installation

# Run directly with npx
npx @snevins/repo-mapper@latest . --tokens 4000

# Or install globally
npm install -g @snevins/repo-mapper
repo-mapper . --tokens 4000

Usage

repo-mapper [paths...] [options]

Options

| Option | Default | Description | |--------|---------|-------------| | -t, --tokens <n> | 4000 | Maximum tokens for output | | -f, --focus <file> | | Files to prioritize (repeatable) | | -o, --output <file> | stdout | Write output to file | | -r, --refresh | false | Ignore cache, re-parse all | | -v, --verbose | false | Print progress info | | --type <lang> | | Filter by language: ts, js, python, go, rust, solidity (repeatable) | | --ignore <pattern> | | Additional ignore patterns (repeatable) | | --include <pattern> | | Only include files matching pattern (repeatable) | | --no-ignore | false | Disable default ignores | | --max-files <n> | 10000 | Maximum files to process |

Examples

# Map current directory with 2000 token budget
repo-mapper . -t 2000

# Focus on specific files you're editing
repo-mapper . -f src/api.ts -f src/types.ts -t 4000

# Only TypeScript files
repo-mapper . --type ts -t 2000

# Only Rust files in a mixed repo
repo-mapper . --type rust -t 2000

# Save to file for LLM prompt
repo-mapper . -t 8000 -o context.md

# Full refresh, verbose output
repo-mapper . -r -v

Output Format

src/ranking.ts:
(Rank: 0.1234)

  15: export function rankDefinitions(tags: Tag[], graph: FileGraph): RankedDefinition[] {
  42: export function buildPersonalization(focusFiles: string[]): Map<string, number> {

src/pagerank.ts:
(Rank: 0.0891)

   8: export function computePageRank(graph: FileGraph, options?: PageRankOptions): Map<string, number> {

Caching

Cache is stored in a global directory to avoid polluting your repository:

| Platform | Location | |----------|----------| | Linux | ~/.cache/repo-mapper/ (or $XDG_CACHE_HOME/repo-mapper/) | | macOS | ~/Library/Caches/repo-mapper/ | | Windows | %LOCALAPPDATA%\repo-mapper\Cache\ |

Each project gets a unique subdirectory based on its path. Files are re-parsed only when modified (mtime-based invalidation).

Clear cache with: rm -rf ~/.cache/repo-mapper (Linux) or equivalent for your platform

How It Works

1. Discover - Find all supported source files
2. Parse - Extract definitions and references using tree-sitter
3. Graph - Build reference graph (file A calls function in file B)
4. Rank - Run PageRank to score files by importance
5. Budget - Binary search to fit top definitions within token limit

Claude Code Plugin

repo-mapper includes a Claude Code plugin with commands and skills.

Installation

# Add to your Claude Code plugins
claude plugins add /path/to/repo-mapper-ts

Commands

| Command | Description | |---------|-------------| | /status | Check if repo-mapper is installed and up to date | | /update-codemap | Generate or update CODEMAP.md with smart language detection |

Skills

The using-repo-mapper skill provides guidance on effective repo-mapper usage patterns.

License

MIT