Repo Map

RepoMap - Command-Line Tool and MCP Server

RepoMap is a powerful tool designed to help, primarily LLMs, understand and navigate complex codebases. It functions both as a command-line application for on-demand analysis and as an MCP (Model Context Protocol) server, providing continuous repository mapping capabilities to other applications. By generating a "map" of the software repository, RepoMap highlights important files, code definitions, and their relationships. It leverages Tree-sitter for accurate code parsing and the PageRank algorithm to rank code elements by importance, ensuring that the most relevant information is always prioritized.

- Aider
- Example Output
- Features
- Installation
- Usage

- Basic Usage
- Advanced Options

> python repomap.py . --chat-files repomap_class.py Chat files: ['/mnt/programming/RepoMapper/repomap_class.py'] repomap_class.py: (Rank value: 10.8111) 36: CACHE_VERSION = 1 39: TAGS_CACHE_DIR = os.path.join(os.getcwd(), f".repomap.tags.cache.v{CACHE_VERSION}") 40: SQLITE_ERRORS = (sqlite3.OperationalError, sqlite3.DatabaseError) 43: Tag = namedtuple("Tag", "rel_fname fname line name kind".split()) 46: class RepoMap: 49: def __init__( 93: def load_tags_cache(self): 102: def save_tags_cache(self): 459: def get_ranked_tags_map_uncached( 483: def try_tags(num_tags: int) -> Tuple[Optional[str], int]: 512: def get_repo_map( utils.py: (Rank value: 0.2297) 18: Tag = namedtuple("Tag", "rel_fname fname line name kind".split()) 21: def count_tokens(text: str, model_name: str = "gpt-4") -> int: 35: def read_text(filename: str, encoding: str = "utf-8", silent: bool = False) -> Optional[str]: importance.py: (Rank value: 0.1149) 8: IMPORTANT_FILENAMES = { 27: IMPORTANT_DIR_PATTERNS = { 34: def is_important(rel_file_path: str) -> bool: 56: def filter_important_files(file_paths: List[str]) -> List[str]: ... ... ...

- Smart Code Analysis: Uses Tree-sitter to parse source code and extract function/class definitions
- Relevance Ranking: Employs PageRank algorithm to rank code elements by importance
- Token-Aware: Respects token limits to fit within LLM context windows
- Caching: Persistent caching for fast subsequent runs
- Multi-Language: Supports Python, JavaScript, TypeScript, Java, C/C++, Go, Rust, and more
- Important File Detection: Automatically identifies and prioritizes important files (README, requirements.txt, etc.)

# Map current directory python repomap.py . # Map specific directory with custom token limit python repomap.py src/ --map-tokens 2048 # Map specific files python repomap.py file1.py file2.py # Specify chat files (higher priority) vs other files python repomap.py --chat-files main.py --other-files src/ # Specify mentioned files and identifiers python repomap.py --mentioned-files config.py --mentioned-idents "main_function" # Enable verbose output python repomap.py . --verbose # Force refresh of caches python repomap.py . --force-refresh # Specify model for token counting python repomap.py . --model gpt-3.5-turbo # Set maximum context window python repomap.py . --max-context-window 8192 # Exclude files with Page Rank 0 python repomap.py . --exclude-unranked

The tool prioritizes files in the following order:
- --chat-files: These files are given the highest priority, as they're assumed to be the files you're currently working on.
- --mentioned-files: These files are given a high priority, as they're explicitly mentioned in the current context.
- --other-files: These files are given the lowest priority and are used to provide additional context.

# Enable verbose output python repomap.py . --verbose # Force refresh of caches python repomap.py . --force-refresh # Specify model for token counting python repomap.py . --model gpt-3.5-turbo # Set maximum context window python repomap.py . --max-context-window 8192 # Exclude files with Page Rank 0 python repomap.py . --exclude-unranked # Mention specific files or identifiers for higher priority python repomap.py . --mentioned-files config.py --mentioned-idents "main_function"

- File Discovery: Scans the repository for source files
- Code Parsing: Uses Tree-sitter to parse code and extract definitions/references
- Graph Building: Creates a graph where files are nodes and symbol references are edges
- Ranking: Applies PageRank algorithm to rank files and symbols by importance
- Token Optimization: Uses binary search to fit the most important content within token limits
- Output Generation: Formats the results as a readable code map

The tool generates a structured view of your codebase showing:

- File paths and important code sections
- Function and class definitions
- Key relationships between code elements
- Prioritized based on actual usage and references

- tiktoken: Token counting for various LLM models
- networkx: Graph algorithms (PageRank)
- diskcache: Persistent caching
- grep-ast: Tree-sitter integration for code parsing
- tree-sitter: Code parsing framework
- pygments: Syntax highlighting and lexical analysis

The tool uses persistent caching to speed up subsequent runs:

- Cache directory:.repomap.tags.cache.v1/
- Automatically invalidated when files change
- Can be cleared with--force-refresh

Currently supports languages with Tree-sitter grammars:

- arduino
- chatito
- commonlisp
- cpp
- csharp
- c
- dart
- d
- elisp
- elixir
- elm
- gleam
- go
- javascript
- java
- lua
- ocaml_interface
- ocaml
- pony
- properties
- python
- racket
- r
- ruby
- rust
- solidity
- swift
- udev
- c_sharp
- hcl
- kotlin
- php
- ql
- scala

This implementation is based on the RepoMap design from the Aider project.

RepoMap can also be run as an MCP (Model Context Protocol) server, allowing other applications to access its repository mapping capabilities.
- The RepoMap MCP server uses STDIO (standard input/output) for communication. No additional configuration is required for the transport layer.
- To set up RepoMap as an MCP server with Cline (or similar tools like Roo), add the following configuration to your Cline settings file (e.g.,cline_mcp_settings.json):

{ "mcpServers": { "RepoMapper": { "disabled": false, "timeout": 60, "type": "stdio", "command": "/usr/bin/python3", "args": [ "/absolute/path/to/repomap_server.py" ] } } }

- Replace"/absolute/path/to/repomap_server.py"with the actual path to yourrepomap_server.pyfile.
- The server will start and listen for requests via STDIO.
- Other applications can then use therepo_maptool provided by the server to generate repository maps. They must specify theproject_rootparameter as an absolute path to the project they want to map.

7/13/2025 - Removed the project.json dependency. Fixed the MCP server to be a little easier for the LLM to work with in terms of filenames.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

A Model Context Protocol (MCP) server that enables AI assistants to integrate with Prometheus Alertmanager

A comprehensive MCP server for tooling interactions(40+) and resource accessibility(60+) plus many useful prompts to interact with Algorand Blockchain.

An MCP server that provides control over Android devices through ADB. Offers device screenshot capture, UI layout analysis, package management, and ADB command execution capabilities.

A Binary Ninja plugin, MCP server, and bridge that seamlessly integrates Binary Ninja with your favorite MCP client.

integration that connects BloodHound with AI through MCP, allowing security professionals to analyze Active Directory attack paths using natural language queries instead of Cypher.

A specialized MCP gateway for LLM enhancement prompts and jailbreaks with dynamic schema adaptation. Provides prompts for different LLMs using an enum-based approach.

Obtains latest dependency details for Clojure libraries.

A Model Context Protocol (MCP) server for CODESYS V3 programming environments.

Analyze large codebases and document collections using high-context models via OpenRouter, OpenAI, or Google AI -- very useful, e.g., with Claude Code