npm package: @snevins/repo-mapper
Description: Generate token-budgeted repo maps for LLM context using tree-sitter and PageRank
Author: Steven Nevins
Latest version: 1.5.3

# repo-mapper

[![npm version](https://img.shields.io/npm/v/@snevins/repo-mapper.svg)](https://www.npmjs.com/package/@snevins/repo-mapper)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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]
```

### 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

```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<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

```bash
# 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