RepoMap

Build faster with AI — without hitting context limits

You've felt this: you're using Cursor, Claude, or Copilot on a real codebase. You ask it to refactor something. It confidently touches the wrong file, misses a dependency three folders away, or invents a function that already exists somewhere else. You spend more time correcting the AI than writing code.

The root cause: your AI doesn't know your codebase. It only sees what fits in its context window — usually a few open files. The moment your project grows beyond a handful of files, the AI starts guessing.

RepoMap fixes this by giving your AI a structured map of your entire codebase — compressed into ~1000 tokens. It's not raw source code. It's a ranked, dependency-aware index of every function, class, and their relationships, with the most important ones surfaced first.

What this means in practice

The workflow

1. Install RepoMap              →  pip install repomap-ai
2. Set up MCP in your IDE       →  repomap init .   (auto-configures Cursor, VS Code, Claude Desktop)
3. Open your AI assistant       →  Ask anything about your codebase
4. AI calls RepoMap tools       →  Gets accurate, token-efficient context automatically

Your AI assistant now knows:

• Which functions exist and where they live

• What calls what (the full call graph)

• Which symbols are most important (PageRank score)

• Where your API routes, CLI commands, and data models are

• What changes when you modify a specific function (blast radius)

You stop correcting hallucinations. You start shipping.

• Features

• Installation

  • Via pip

  • Via npm / npx

  • From source

• Quick Start

• CLI Reference

• MCP Setup

  • One-command setup

  • Cursor

  • VS Code

  • Claude Desktop

  • MCP Tools

• Configuration

• Architecture

• Contributing

• License

Features

• 🌳 Tree-sitter parsing for Python, TypeScript, JavaScript (Go, Rust, Java, Ruby, C/C++ via extras)

• 🔗 Typed dependency graph — calls, imports, reads, writes, extends, implements

• 📊 PageRank ranking to surface the most important symbols first

• 💰 Token-budget-aware output — never exceeds your configured limit

• 🎯 Data model detection — Pydantic, dataclass, SQLAlchemy

• 🚪 Entry point detection — CLI commands, API routes, main() functions

• 📄 Multiple output formats — Markdown, JSON, XML

• 🗺️ Interactive HTML visual explorer with WebGL rendering (handles 10k+ nodes)

• 🤖 MCP server for Cursor, VS Code, Claude Desktop

• 👁️ Incremental file watcher — updates the map as you code

Installation

Via pip

Requires Python 3.11+.

pip install repomap-ai

With optional extras:

# Full install: visual explorer + MCP server + performance backend
pip install "repomap-ai[visual,mcp,scale]"

# Additional language support (Go, Rust, Java, Ruby, C/C++)
pip install "repomap-ai[languages]"

Recommended for global CLI use:

pipx install repomap-ai

Verify installation:

repomap --help

Via npm / npx

No Python setup needed — the npm package auto-installs the Python backend on first run.

# Run instantly without installing anything globally
npx repomap-ai generate .

# Or install globally to get the `repomap` command
npm install -g repomap-ai
repomap generate .

Note: Python 3.11+ must still be available on your PATH. The npm package is a thin wrapper that auto-runs pip install repomap-ai on install.

From source (development)

git clone https://github.com/tushar22/repomap.git
cd repomap

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate       # Windows: .venv\Scripts\activate

# Install in editable mode with all dev extras
pip install -e ".[dev,visual,mcp,scale,languages]"

# Run tests
pytest tests/ -v

Quick Start

# cd into any repository
cd /path/to/your/project

# Generate a token-efficient map (outputs to stdout)
repomap generate .

# Save to file with a larger token budget
repomap generate . --max-tokens 4000 --output map.md

# Focus on a specific function and its dependencies
repomap generate . --around "UserService.authenticate"

# Open the interactive visual graph in your browser
repomap visual . -o graph.html && open graph.html

# Set up MCP for your AI IDE (one command)
repomap init .

CLI Reference

repomap generate

Generate a token-efficient repository map.

repomap generate [PATH] [OPTIONS]

Examples:

# Default: markdown, 1000 tokens
repomap generate .

# JSON output focused on a class
repomap generate . --format json --around "PaymentService" --output context.json

# Scoped to a subdirectory, XML format for Claude
repomap generate . --scope src/api --format xml --max-tokens 4000

repomap init

Generate IDE config files for MCP integration. Supports Cursor, VS Code, and Claude Desktop in one command.

repomap init [PATH]

This auto-creates:

• .cursor/mcp.json — for Cursor

• .vscode/mcp.json — for VS Code / GitHub Copilot

• ~/Library/Application Support/Claude/claude_desktop_config.json — for Claude Desktop (if installed)

repomap serve

Start the MCP server.

# stdio transport (used by Cursor, VS Code, Claude Desktop)
repomap serve . --transport stdio

# HTTP transport (for tools that support SSE)
repomap serve . --transport http --port 3847

repomap visual

Generate a self-contained interactive HTML graph explorer (WebGL-accelerated, handles 10k+ symbols).

repomap visual . -o graph.html

Open the HTML file in any browser — no server needed.

repomap watch

Incrementally update the symbol store as files change.

repomap watch .

repomap stats

Show symbol store statistics.

repomap stats .

repomap diff

Show changed symbols and their blast radius (affected callers/dependents) since a git ref.

repomap diff HEAD~1 .
repomap diff main . --depth 3

MCP Setup

RepoMap runs as a local MCP server — your code never leaves your machine.

One-command setup

# Install
pip install repomap-ai
# or: npm install -g repomap-ai

# cd into your project
cd /path/to/your/project

# Auto-configure all supported IDEs at once
repomap init .

Then restart your IDE. Done.

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "repomap": {
      "command": "repomap",
      "args": ["serve", ".", "--transport", "stdio"]
    }
  }
}

Restart Cursor. The MCP tools will appear in the AI panel.

VS Code

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "repomap": {
      "type": "stdio",
      "command": "repomap",
      "args": ["serve", ".", "--transport", "stdio"]
    }
  }
}

Restart VS Code. Works with GitHub Copilot and any MCP-compatible extension.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "repomap": {
      "command": "repomap",
      "args": ["serve", "--transport", "stdio", "/path/to/your/project"]
    }
  }
}

Windows path: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop.

MCP Tools

Once connected, your AI assistant has access to these tools:

Configuration

RepoMap reads config from pyproject.toml or .repomaprc at the repository root.

pyproject.toml

[tool.repomap]
max_tokens = 1000
output_format = "markdown"
exclude_patterns = ["**/node_modules/**", "**/.venv/**", "**/.git/**"]

.repomaprc

max_tokens = 1000
output_format = markdown
exclude_patterns = **/node_modules/**, **/.venv/**, **/.git/**

Architecture

Source Files → Parser → Symbol Store → Graph Builder → PageRank → Formatter → Output

1. Parser — tree-sitter grammars extract symbols (functions, classes, methods) and typed edges from source files. Results are cached in .repomap/symbols.db.

2. Graph — directed dependency graph built with NetworkX. Edges are typed (calls, imports, reads, writes, extends, implements) and weighted by confidence.

3. Ranker — PageRank over the dependency graph scores each symbol by structural importance. Entry points and data models receive rank boosts.

4. Formatter — ranked symbols serialized to Markdown/JSON/XML, pruned to fit within the token budget using tiktoken for accurate counting.

Contributing

Contributions are welcome! Here's how to get started.

1. Fork and clone

git clone https://github.com/YOUR_USERNAME/repomap.git
cd repomap

2. Set up your dev environment

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev,visual,mcp,scale]"

3. Run the tests

pytest tests/ -v

All tests must pass before submitting a PR.

4. Make your changes

• Bug fixes — open a PR directly with a clear description

• New features — open an issue first to discuss the approach

• New language support — add a tree-sitter query file under repomap/parser/queries/ and register it in tree_sitter_parser.py

5. Code style

• Follow PEP 8 (enforced by ruff if you have it installed)

• Type annotations on all public functions

• Docstrings for new public classes and methods

6. Submit a Pull Request

• Target the main branch

• Describe what changed and why

• Reference any related issues (Fixes #123)

Project structure

repomap/
├── parser/          # Tree-sitter parsers + .scm query files per language
├── graph/           # Graph builder, models, PageRank ranker
├── formatter/       # Markdown, JSON, XML output formatters
├── core/            # Engine, config, symbol store (SQLite)
├── integrations/    # CLI (Typer), MCP server, file watcher, diff
├── visual/          # WebGL HTML explorer generator + template
├── intelligence/    # LLM enrichment, hot path detection, narratives
└── data_models/     # Pydantic/dataclass/SQLAlchemy detector
tests/
npm/                 # npm wrapper package

Reporting bugs

Open an issue at github.com/tushar22/repomap/issues with:

• Your OS and Python version

• The command you ran

• The full error output

License

MIT — see LICENSE for details.