Cartog
Map your codebase. Navigate by graph, not grep.
Cartog pre-computes a code graph — symbols, calls, imports, inheritance — and lets you query it in microseconds. Use it from the CLI, as an MCP server for AI agents, or both. Everything runs locally: no API calls, no cloud, no data leaves your machine.
Documentation site →
Why Cartog
| grep/cat/find | Cartog |
|---|
| Query latency | multi-step | 8-450 μs |
| Recall (completeness) | 78% | 97% |
| Transitive analysis | impossible | impact --depth 3 traces callers-of-callers |
| Semantic search | no | local ONNX / Ollama |
| Privacy | local | 100% local — no remote calls |
Measured across 13 scenarios, 5 languages (full benchmark suite).
What you get
- Single binary, self-contained —
cargo install cartog and you're done. No Docker, no config.
- 100% local — tree-sitter parsing + SQLite storage + local embeddings. Your code never leaves your machine.
- Dual search — keyword search (sub-ms, symbol names) and semantic search (natural language). Configurable embedding providers (local ONNX or Ollama).
- Impact analysis —
cartog impact --depth 3 traces callers-of-callers. Know the blast radius before you change anything.
- Live index —
cartog watch auto re-indexes on file changes. Always query fresh data.
- Optional LSP precision — auto-detects language servers on PATH to boost edge resolution from ~25% to ~42-81%.
For LLM agents
- MCP server —
cartog serve exposes 12 tools over stdio. Plug into Claude Code, Cursor, Windsurf, Zed, or any MCP-compatible agent.
- Agent skill — teaches your agent when and how to use Cartog. Search routing, refactoring workflows, fallback heuristics.
- Token efficient — 83% fewer tokens per query vs grep/cat workflows. One
refs call replaces 6+ discovery steps.
Quick Start
cargo install cartog
cd your-project
cartog index . # build the graph (~95ms for 4k LOC, incremental)
cartog search validate # find symbols by name (sub-millisecond)
cartog refs validate_token # who calls/imports/references this?
cartog impact validate_token # what breaks if I change this?
Add semantic search (optional, still fully local)
cartog rag setup # download embedding + re-ranker models (~1.2GB, one-time)
cartog rag index . # embed all symbols + documents into sqlite-vec
cartog rag search "authentication token validation" # natural language queries
Indexes both code (functions, classes, methods) and Markdown documents (READMEs, design docs, API docs). Returns code by default; use --kind document for docs or --kind all for both.
Models are downloaded once to ~/.cache/cartog/models/ and run locally via ONNX Runtime. No API keys, no network calls at query time.
Using Ollama instead? Configure .cartog.toml with [embedding] provider = "ollama" and skip rag setup — models are managed by Ollama. See Configuration.
Install
From crates.io
cargo install cartog # core (heuristic resolution only)
cargo install cartog --features lsp # + LSP-based resolution (recommended)
cargo install cartog --features ollama-embedding # + Ollama embedding support
The lsp feature adds ~50KB to the binary. It auto-detects language servers on PATH (rust-analyzer, pyright, typescript-language-server, gopls, ruby-lsp, solargraph) and uses them to resolve edges that heuristic matching can't. No extra config needed — if a server is on PATH, it's used automatically.
Pre-built binaries
Download from GitHub Releases:
# macOS (Apple Silicon)
curl -L https://github.com/jrollin/cartog/releases/latest/download/cartog-aarch64-apple-darwin.tar.gz | tar xz
sudo mv cartog /usr/local/bin/
# macOS (Intel)
curl -L https://github.com/jrollin/cartog/releases/latest/download/cartog-x86_64-apple-darwin.tar.gz | tar xz
sudo mv cartog /usr/local/bin/
# Linux (x86_64)
curl -L https://github.com/jrollin/cartog/releases/latest/download/cartog-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv cartog /usr/local/bin/
jrollin