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

``bash


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

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

$3

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

$3

`bash


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 {

src/pagerank.ts:
(Rank: 0.0891)

8: export function computePageRank(graph: FileGraph, options?: PageRankOptions): Map {
`

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.

$3

`bash


Add to your Claude Code plugins


claude plugins add /path/to/repo-mapper-ts
`

$3

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

$3

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

License

MIT