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.
This server cannot be deployed
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.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
