Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CodeMap who calls processPayment and what breaks if I change it?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Turn any repository into a queryable structural graph.Stop paying agents to read every file — let them query the map.
Quick Start • MCP Tools • Benchmark • How It Works • CLI Reference
Every coding agent today explores repositories the same way: grep → read file → read another file → repeat. For a mid-size codebase this burns hundreds of thousands of tokens before the agent even starts fixing your bug.
CodeMap replaces that with a pre-built knowledge graph:
Naive Agent (grep + read) | CodeMap (graph queries) | |
5 structural queries | ~412,000 tokens | ~3,400 tokens |
Latency (5 queries) | ~18 s (file I/O) | ~120 ms |
Cost (GPT-4 class) | ~$12.36 | ~$0.10 |
Incremental update | Full re-read | Single-file patch |
📊 Benchmark measured on a ~800-file Python/TS monorepo. See
codemap benchfor reproducible numbers on your repo.
Related MCP server: codebase-rag
🔍 9 MCP tools — find_definition, find_callers, blast_radius, impact_analysis, and more
🌳 Tree-sitter + regex fallback — works out-of-the-box, no native build required
⚡ Incremental indexing — file hashes + watcher; only changed files are re-parsed
💾 Zero-infra graph store — SQLite + NetworkX; no Neo4j, no Docker, no cloud
🧩 Language support — Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, Ruby, PHP, C#
🔌 Any MCP client — Claude Desktop, Cursor, Windsurf, OpenCode, Continue
📈 Reproducible benchmark — codemap bench prints per-query token savings
pip install codemap
# or with uv
uv pip install codemap
# optional: tree-sitter acceleration (recommended)
pip install tree-sitter tree-sitter-languagescd /path/to/your/repo
codemap index # incremental — skips unchanged files
codemap index --full # force full rebuild
codemap stats # index stats + token-savings estimatecodemap query find_definition --name authenticate
codemap query find_callers --name processPayment --limit 20
codemap query blast_radius --name UserService --file src/services/user.py
codemap query impact_analysis --file src/auth/middleware.py
codemap query search_symbols --query "handler" --kind functionAdd to claude_desktop_config.json:
{
"mcpServers": {
"codemap": {
"command": "codemap",
"args": ["serve", "--root", "/absolute/path/to/your/repo"]
}
}
}Restart Claude Desktop. The 9 CodeMap tools appear automatically.
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"codemap": {
"command": "codemap",
"args": ["serve", "--root", "/absolute/path/to/your/repo"]
}
}
}Any MCP-compatible client that supports stdio transport works. Point it at:
command: codemap
args: ["serve", "--root", "/path/to/repo"]Or set CODEMAP_ROOT and CODEMAP_DB environment variables.
Generate the config snippet automatically:
codemap mcp-config /path/to/repocodemap watch # watches cwd, re-indexes on saveTool | What it does | Typical token cost |
| Locate symbol definition (file, line, signature, docstring) | ~180 tokens |
| Who calls this function? (BFS depth 1–N) | ~420 tokens |
| What does this function call? | ~420 tokens |
| Transitive dependents if this symbol/file changes | ~680 tokens |
| File-level impact: affected files, tests, risk score | ~850 tokens |
| List symbols in a file or of a kind | ~500 tokens |
| Fuzzy name search across the repo | ~300 tokens |
| Index stats + token-savings estimate | ~150 tokens |
| Deep explain: definition + callers + callees + file context | ~950 tokens |
Total for 5 typical queries: ~3,400 tokens vs ~412k naive.
Run on your repo:
codemap benchExample output on this repo (codemap itself, ~12 files):
┌──────────────────────────────┬──────────────┬──────────────┬─────────┐
│ Query │ Graph tokens │ Naive tokens │ Savings │
├──────────────────────────────┼──────────────┼──────────────┼─────────┤
│ find_definition('__init__') │ 312 │ 18420 │ 98.3% │
│ find_callers('index') │ 410 │ 22100 │ 98.1% │
│ blast_radius('GraphStore') │ 680 │ 45200 │ 98.5% │
│ search_symbols('parse') │ 385 │ 18420 │ 97.9% │
│ get_stats() │ 150 │ 4200 │ 96.4% │
└──────────────────────────────┴──────────────┴──────────────┴─────────┘
Overall savings: 98.1% — Graph queries use ~1,937 tokens vs ~108,340 naiveThe naive estimate sums the sizes of all files containing the target substring (what an agent would
grep+read). Graph queries return only structured JSON with file/line pointers.
For a larger monorepo (~800 files, ~180k LOC), the gap widens to ~99%.
Repo on disk
│
▼
┌──────────┐ tree-sitter / regex ┌────────────┐
│ Discover │ ─────────────────────────► │ Parse │ ──► Symbols + Edges
│ Files │ │ (parallel)│
└──────────┘ └────────────┘
│
▼
┌──────────┐
│ SQLite │ ◄── file hashes (incremental)
│ Graph │ NetworkX mirror (traversals)
└──────────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
CLI `query` MCP `serve` `watch` (watchdog)Nodes: file, class, function, method, variable, import, interface, enum
Edges: contains, defines, imports, calls, inherits, references, tested_by
Incremental indexing uses SHA-256 file hashes — unchanged files are skipped entirely.
codemap index [ROOT] [--db PATH] [--full] [--workers N] Index a repo
codemap watch [ROOT] [--db PATH] Watch + auto re-index
codemap serve [--root PATH] [--db PATH] Start MCP server (stdio)
codemap query TOOL [--name NAME] [--file FILE] [--kind KIND] [--limit N] [--json]
codemap stats [--db PATH] [--root PATH] Show index stats
codemap bench [ROOT] [--db PATH] Run token benchmark
codemap mcp-config [ROOT] Print MCP client configpip install -e ".[dev]"
pytest -vLSP hover integration (jump-to-definition from editor)
Semantic search layer (embeddings over docstrings)
Cross-repo graph federation
VS Code extension
codemap viz — interactive graph visualization (HTML export)
PRs welcome! Please run ruff and pytest before submitting.
ruff check codemap/
pytestMIT — see LICENSE.
If CodeMap saved you tokens, give it a ⭐ — it helps others discover it.
Built for the agentic era. Less reading, more shipping.
Codebase graphs, caller impact analysis, and recorded project context for AI coding agents.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.