Code Graph Navigator

Query your codebase as graph Coding agent optimized

Single Rust binary, answer in microseconds, 12 languages.
True local semantic search, 100% local. MCP server built in.

⚡ 8μs
Query latency*
🎯 97%
Symbol recall*
🌐 12
Languages supported
🔍 2
Keyword + semantic search
🔒 100%
Local. Your code stays private

* Measured across 13 scenarios. Latency is the outline-query median on the Python fixture; 97% recall requires a matching language server on PATH
Benchmark suite →

Cartog demo
Animated demo: cartog init, index, map, search, refs, impact in a terminal
Quick Install
macOS / Linux curl -fsSL https://jrollin.github.io/cartog/install.sh | sh
Claude Code plugin /plugin marketplace add jrollin/cartog

More install options ↓

Why Cartog ↓ Agents ↓
How it works

Two commands to get started.

cartog init scaffolds .cartog.toml.
cartog index builds the graph.

your-repo
$ cartog init + .cartog.toml: created from template Next steps: 1. Edit .cartog.toml if you want to change defaults (DB path, embedding provider). 2. Run `cartog index` to build the code graph. $ cartog index Indexed 142 files (0 unchanged), 3891 symbols, 8217 edges in 95ms # Optional — wire cartog into your editor for AI agents $ cartog ide --scope project + cursor (project, .cursor/mcp.json): created + vscode (project, .vscode/mcp.json): created

⚙️ cartog init

Drops a commented .cartog.toml template. Config only — re-runs are a no-op, your toml is never overwritten.

📚 cartog index

tree-sitter parses 12 languages into a local SQLite file. Incremental on re-runs; only changed files re-parse. Pair with cartog watch for auto-refresh.

🛠️ cartog ide (optional)

Skip this if you only use the CLI. Need MCP in Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, OpenCode, Windsurf, Zed, Claude Desktop, Antigravity, Kiro, or Hermes Agent? Run it once per machine.

CLI-only users stop at step 2. The third verb is purely for plugging cartog into MCP-aware editors.

🩺 cartog doctor — health check

Run it after install or when something looks off. Reports git, config, database, and model status.

cartog doctor
$ cartog doctor [+] git: git repository at /your/repo [+] config: loaded from .cartog.toml [+] database: 142 files, 3891 symbols [+] embedding: local model cached [+] reranker: jina-reranker-v1-turbo-en cached All 5 checks passed
Features

Navigate your codebase, not file contents.

Single binary, zero config, zero dependencies.

⚡

Zero dependencies

Single binary + SQLite file. No Docker, no language servers required, no graph databases. cargo install and you're done.

🔄

Live index

cartog watch auto re-indexes on file changes. Debounced, incremental, near-instant. Always query fresh data.

🔍

Dual search

Keyword search (sub-ms, symbol names) + semantic search (natural language). CPU-only local embeddings by default (ONNX via fastembed); optional Ollama or any OpenAI-compatible /v1 endpoint for hosted or GPU-backed embedding.

🎯

Impact analysis

cartog impact --depth 3 traces callers-of-callers instantly. Know the blast radius before you change anything.

🔬

LSP precision, built in

Auto-detects language servers on PATH. Boosts edge resolution from ~25% to ~44–81%. Works without them, better with them.

🔒

100% local

tree-sitter parsing, SQLite storage, local embeddings. No API keys, no telemetry. Secrets are redacted and sensitive files (.env, keys) skipped before they reach the index. Works in air-gapped environments.

Languages

12 languages supported — more coming

Python TypeScript JavaScript Rust Go Ruby Java PHP Dart Swift Kotlin Markdown
Why Cartog

Code is a graph. Query it like one.

Pre-compute the structure once, then answer any question in microseconds.

01

Grep can't trace what breaks

Transitive impact analysis is impossible with grep. cartog impact --depth 3 traces callers-of-callers instantly. Know the blast radius before you change anything.

02

Structured answers, not file dumps

One refs call returns every caller, importer, and type reference — with file paths and line numbers. No parsing output, no false positives.

03

Your code stays on your machine

tree-sitter parsing, SQLite storage, local embeddings. No API keys, no telemetry, no cloud. Hardcoded secrets are redacted and sensitive files skipped before indexing. Works in air-gapped environments.

grep / cat / find Language server (LSP) Cartog
Transitive analysis impossible limited impact --depth 3
Query latency multi-step seconds 8-450 μs
Setup none per-language server single binary
Startup time instant seconds to minutes instant
Language coverage any 1 per server 12 languages
Semantic search no no local ONNX / Ollama / OpenAI
Privacy local local 100% local

Measured across 13 scenarios, 10 languages. Benchmark suite →

Alternatives

Why not...

01

grep / ripgrep

Great for string literals and config values. But grep can't trace call chains, can't do transitive impact analysis, and floods your context with raw text. Cartog returns structured, ranked, deduplicated results — one refs call replaces 6+ discovery steps.

02

A language server

LSPs give perfect precision but require per-language setup, take seconds to start, and only cover one language at a time. Cartog covers 12 languages with one binary and answers in microseconds. When you need LSP precision, cartog uses it as an optional layer.

03

Other code-graph indexers

Most ship a runtime to install (Python, Node) and stop at keyword search. Cartog is a single static Rust binary with three things they lack: true embedding-based semantic search (vector KNN + cross-encoder re-ranking, not keyword matching), pluggable embedding providers (local ONNX, Ollama, or any OpenAI-compatible endpoint), and S3 index sync (cartog push / pull) to share a pre-built graph across a team or CI. All 100% local by default.

LLM Agents

Supercharge your AI coding agent

83% fewer tokens per query, 97% recall*. Your agent queries the graph instead of grepping blind.

Wires into your editor with cartog ide

Claude Code Cursor VS Code Claude Desktop Codex CLI Gemini CLI OpenCode Windsurf Zed Antigravity Kiro Hermes Agent

Claude Code, VS Code, and Kiro get both project-scoped MCP files in your repo and user-scope configs; Cursor is project-scoped; the rest get user-scope configs in your home directory. Only editors actually installed are touched.

01

One command to wire it in

cartog ide writes cartog serve into installed editors (Cursor, VS Code, Codex CLI, Gemini CLI, OpenCode, Windsurf, Zed, Claude Desktop, Antigravity, Kiro, Hermes Agent). Idempotent merge, existing MCP servers preserved. Skip it if you only use the CLI.

02

16 MCP tools

cartog serve exposes cartog_map, cartog_search, cartog_refs, cartog_impact, cartog_rag_search, and 11 more. Each tool description tells the agent when (and when not) to use it.

03

Agent skill

The bundled skill teaches your agent when and how to use cartog — search routing, refactoring workflows, fallback heuristics — so it picks the right tool first.

Integration Setup What it does
CLI bootstrap cartog init + cartog index Scaffold .cartog.toml, then build the graph. CLI-only flow.
Editor MCP wiring (optional) cartog ide [--client X] 12 clients across 6 config shapes (incl. Codex TOML, Hermes YAML); idempotent, dry-run-able
Claude Code plugin /plugin marketplace add jrollin/cartog
/plugin install cartog@cartog-plugins		 Skill + MCP + auto-setup, all-in-one
MCP server (manual) cartog serve --watch 16 tools over stdio, live index + auto semantic embedding
Agent skill npx skills add jrollin/cartog Behavioral rules for any compatible agent
CLI (any agent with bash) cargo install cartog Direct commands — works with any tool-using LLM

See MCP Server docs and Agent Skill docs for per-client setup. Supported clients: Claude Code (project + user), Claude Desktop, Codex CLI, Cursor, Gemini CLI, OpenCode, VS Code (project + user), Windsurf, Zed, Antigravity, Kiro (project + user), Hermes Agent.

MCP Server

A code graph your agent can call.

cartog serve speaks the Model Context Protocol over stdio: 16 tools any MCP client launches as a subprocess. No HTTP port, no daemon, no API keys. The graph stays on your machine.

wire it in once
# point every installed editor at cartog (idempotent) $ cartog ide + cursor (project, .cursor/mcp.json): created + vscode (project, .vscode/mcp.json): created + claude-code (project, .mcp.json): created # the editor now spawns this on demand: $ cartog serve --watch # 16 tools + live re-index

🔌 One command to wire it in

cartog ide is the only verb that writes MCP configs. It merges cartog serve into Claude Code, Cursor, VS Code, Codex CLI, Gemini CLI, OpenCode, Windsurf, Zed, Claude Desktop, Antigravity, Kiro, and Hermes Agent. Existing servers preserved, dry-run-able.

🧰 16 tools, typed output

14 read tools (map, search, refs, impact, rag_search, …) ship readOnlyHint and declare an outputSchema, so clients skip approval prompts and get validated structuredContent. 2 write tools build the index.

📡 Live + progress-aware

--watch re-indexes on file changes and auto-refreshes semantic embeddings when the repo already has them (no --rag needed). cartog_index and cartog_rag_index emit MCP notifications/progress so the client can show a progress bar.

Manual config (any MCP client)
command cartog serve

Full per-client JSON/TOML in the MCP Server docs →

Articles

How cartog works

A series on the internals, from the code graph to semantic search.

01

Tree-sitter and code graphs: navigating code better than grep

Parsing code with tree-sitter into a SQLite symbol graph, cutting the tokens an agent burns versus grep's line-by-line scans.

🇬🇧 Read article 🇫🇷 Lire l'article
02

Semantic code search with RAG and ONNX

Local BGE-small embeddings, FTS5 + vector KNN fused with reciprocal rank fusion, then cross-encoder re-ranking, all on CPU.

🇬🇧 Read article 🇫🇷 Lire l'article
03

Language Server Protocol to sharpen a code graph

Tapping language servers like rust-analyzer and pyright to lift edge-resolution precision from 25–37% to 44–81%.

🇬🇧 Read article 🇫🇷 Lire l'article
04

Incremental indexing with a Merkle tree

Merkle hashing plus multi-level file filtering to re-index only changed symbols, dropping re-index time from seconds to milliseconds.

🇬🇧 Read article 🇫🇷 Lire l'article
Install

Get started in seconds

Pick one install method below — these are alternatives, not steps. Once cartog is on your PATH, run cartog init + cartog index in any repo.

① Install script — macOS / Linux, no Rust required

curl -fsSL https://jrollin.github.io/cartog/install.sh | sh

Detects your OS + architecture, downloads the matching binary from the latest GitHub Release, verifies its SHA-256, and installs to /usr/local/bin (or ~/.local/bin if non-root). Override the target with CARTOG_INSTALL_DIR, pin a version with CARTOG_VERSION. Audit the script: scripts/install.sh.

② From crates.io — Rust toolchain required

cargo install cartog                              # default: LSP + S3 sync + Ollama + OpenAI
cargo install cartog --no-default-features        # minimal: drops LSP, S3, Ollama, OpenAI
cargo install cartog --no-default-features --features lsp  # LSP only

LSP, S3 index sync, and the Ollama + OpenAI-compatible providers are all enabled by default. Local ONNX stays the default embedding provider; set provider = "ollama" or provider = "openai" in .cartog.toml to use a remote endpoint. Disable LSP at runtime with --no-lsp, or strip features at build time with --no-default-features.

③ Pre-built binaries — manual download

# 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/

# 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/

All four targets + SHA256SUMS on GitHub Releases (macOS arm64, Linux arm64/x86_64, Windows x86_64).

Already in Claude Code? /plugin marketplace add jrollin/cartog bundles install + skill + MCP. Use any agent? npx skills add jrollin/cartog adds the behavioural skill alongside any install method above.

Start mapping your codebase

Open source, free forever. One command to install, one to wire it up.

curl -fsSL https://jrollin.github.io/cartog/install.sh | sh

Then cartog init + cartog index in your repo. Read the documentation →