RepoMap

RepoMap uses a priority system to decide which files to include in the map when token limits are reached. You can control this using the following flags:

1. --chat-files: Highest priority. Use this for files you are currently working on.
2. --mentioned-files: High priority. Use this for files explicitly mentioned in your current context.
3. --other-files: Lowest priority. Used to provide additional context.

Example of specifying priority:

python repomap.py --chat-files main.py --other-files src/

RepoMap generates a codebase map through the following pipeline:

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

Install the necessary dependencies for RepoMap using pip:

pip install -r requirements.txt

RepoMap can run as a Model Context Protocol (MCP) server using STDIO. To use it with tools like Cline, add the following configuration to your cline_mcp_settings.json:

Note: You must replace the command and args path with the absolute path to your Python executable and the repomap_server.py file.

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

To start the MCP server, run the server script directly:

python repomap_server.py

Once running, the server listens via STDIO. Clients can call the repo_map tool, which requires a project_root parameter (an absolute path to the project being mapped).

RepoMap can be used via the command line to generate a map of your codebase. Use python repomap.py followed by the target directory or files.

Common tasks:

• Map the current directory: python repomap.py .
• Map a specific directory with a custom token limit: python repomap.py src/ --map-tokens 2048
• Map specific files: python repomap.py file1.py file2.py

# 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

RepoMap supports any language with a Tree-sitter grammar, including:

• Python, JavaScript, TypeScript, Java, C/C++, Go, Rust
• C#, PHP, Ruby, Swift, Kotlin, Scala
• Solidity, Lua, Dart, Elixir, etc.

Use these flags to fine-tune the mapping process:

• --mentioned-files <path>: Specify files that should have high priority.
• --mentioned-idents <identifier>: Specify specific identifiers (like function names) for higher priority.
• --verbose: Enable verbose output.
• --force-refresh: Force refresh of the persistent caches.
• --model <model_name>: Specify the model used for token counting (e.g., gpt-3.5-turbo).
• --max-context-window <int>: Set the maximum context window size.
• --exclude-unranked: Exclude files that have a PageRank of 0.

# Example of advanced usage
python repomap.py . --mentioned-files config.py --mentioned-idents "main_function" --max-context-window 8192 --exclude-unranked

The RepoMapServer provides two primary tools via the Model Context Protocol (MCP) to help LLMs understand a codebase: repo_map for generating a high-level structural overview and search_identifiers for finding specific code elements. Both tools require an absolute path to the project_root.

# Example conceptual usage of the tools via an MCP client

# 1. Generate a repository map
await repo_map(
    project_root="/abs/path/to/project",
    chat_files=["src/main.py"],
    token_limit=8192
)

# 2. Search for a specific identifier
await search_identifiers(
    project_root="/abs/path/to/project",
    query="MyClassName"
)

When search_identifiers succeeds, it returns a dictionary with the following structure:

{
  "results": [
    {
      "file": "path/to/file.py",
      "line": 42,
      "name": "identifier_name",
      "kind": "def" | "ref",
      "context": "string containing the code snippet with context lines"
    }
  ]
}