cartog

Cartog

Map your codebase. Navigate by graph, not grep.

~280 tokens per query vs ~1,700 for grep+read · 97% recall · 8 µs–20 ms latency · 12 languages.

Cartog pre-computes a code graph — symbols, and the calls, imports, and inheritance between them — so you can query structure instantly instead of grepping for text. Ask "who calls this?", "what breaks if I change it?", or "find the auth logic" and get a ranked, structured answer in microseconds.

Use it from the CLI for day-to-day navigation, or as an MCP server so AI agents query the graph instead of flooding their context with raw file dumps — at a fraction of the token cost. One static binary, one SQLite file. No Python, no pip, no Docker, no cloud: 100% local by default.

Documentation site

Contents

• Quick Start
• Why Cartog
• What You Get
• Install
• Commands
• MCP Server Setup
• Supported Languages
• Configuration
• Privacy
• Troubleshooting
• Articles

Quick Start

curl -fsSL https://jrollin.github.io/cartog/install.sh | sh   # or: cargo install cartog
cd your-project
cartog init                   # 1. scaffold .cartog.toml
cartog index                  # 2. build the code graph

That's it for CLI use. Two commands.

If you want MCP wired into your editor (Claude Code, Cursor, VS Code, Claude Desktop, Codex CLI, Gemini CLI, OpenCode, Windsurf, Zed, Antigravity, Kiro, Hermes Agent), add one more:

cartog ide                    # optional — only if you want editor integration

All three commands are idempotent.

Now query:

cartog search validate        # find symbols by name         (sub-ms)
cartog refs validate_token    # who calls this?              (< 500 µs)
cartog impact validate_token  # what breaks if I change it?  (< 20 ms)
cartog outline src/auth.py    # file structure, no cat       (< 15 µs)

Teach your agent to use cartog

Wiring MCP is half the job. The other half is telling the agent when to prefer cartog over grep + read. Drop the snippet from docs/agent-snippet.md into your project's AGENTS.md, CLAUDE.md, .cursor/rules/, or equivalent, and the agent will route "where is X?" / "who calls X?" / "what breaks if I change X?" through cartog's 16 MCP tools instead of flooding context with raw text.

Why Cartog

Every code navigation tool makes you choose: fast but shallow (grep), or precise but slow (language servers). Cartog gives you both.

	grep / cat / find	Language servers	Cartog
Query speed	depends on codebase size	seconds to start	8-450 µs
Transitive analysis	impossible	partial	impact --depth 5
Setup	none	per-language config	one binary, zero config
Languages	all (text)	one per server	12 languages, one tool
Token cost (LLM context)	~1,700 tokens/query	n/a	~280 tokens/query
Recall (completeness)	78%	~100%	97% *
Privacy	local	local	100% local

Measured across 13 scenarios, 10 languages (benchmark suite).

* 97 % recall requires a matching language server on PATH. The default build ships LSP support; heuristic-only resolution (no server found, or --no-lsp) lands around 25–37 %, with specifics varying by language.

What You Get

Fast structural queries

Pre-computed graph means no re-reading files, no multi-step discovery.

cartog search parse              # symbol name lookup (sub-ms)
cartog refs UserService          # all callers, importers, inheritors
cartog callees authenticate      # what does this function call?
cartog impact SessionManager     # blast radius — callers-of-callers, depth N
cartog hierarchy BaseService     # inheritance tree
cartog deps src/routes/auth.py   # file-level imports
cartog changes --commits 5       # symbols affected by recent git commits
cartog map --tokens 4000         # codebase overview, ranked by centrality

Semantic search (optional, still fully local)