v0.13.1 View changelog →

Quick Start

cargo install cartog
cd your-project
cartog index .               # build the graph (~95ms for 4k LOC)
cartog search validate       # find symbols by name (sub-ms)
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 models (~1.2GB, one-time)
cartog rag index .           # embed all symbols + documents
cartog rag search "authentication token validation"

Indexes both code (functions, classes, methods) and Markdown documents (READMEs, design docs, API docs). Models are downloaded once to ~/.cache/cartog/models/ and run locally via ONNX Runtime. No API keys needed.

Using Ollama instead? Add this to your .cartog.toml and skip rag setup:

[embedding]
provider = "ollama"

See Embedding Providers for full setup.

Search Modes

Cartog offers two search modes that complement each other:

Recommended Workflow

cartog index .          # 1. build the graph
cartog search foo       # 2. discover exact symbol names
cartog refs foo         # 3. find all usages
cartog callees foo      # 4. see what it depends on
cartog impact foo       # 5. assess blast radius
cartog index .          # 6. re-index after changes

Configuration

Cartog works with zero configuration. Optionally, place a .cartog.toml at your project root to customize database path, embedding provider, and re-ranking.

# .cartog.toml — full reference

[database]
path = "~/.local/share/cartog/myproject.db"

# Embedding provider (optional — defaults to local ONNX)
[embedding]
provider = "local"               # "local" (default) or "ollama"
model = "BAAI/bge-small-en-v1.5" # model name (provider-specific)
dimension = 384                  # auto-detected for built-in models

# Local provider: asymmetric model prefixes
[embedding.local]
query_prefix = "search_query: "
document_prefix = "search_document: "

# Ollama provider settings
[embedding.ollama]
base_url = "http://localhost:11434"
model = "nomic-embed-text"

# Reranker (optional — defaults to local cross-encoder)
[reranker]
provider = "local"               # "local" (default) or "none"

Database path resolution priority: --db flag / CARTOG_DB env > .cartog.toml > git root auto-detection > cwd fallback.

Embedding Providers

Semantic search requires an embedding provider. Two options:

Example: Ollama with GPU acceleration

# 1. Install with Ollama feature
cargo install cartog --features ollama-embedding

# 2. Start Ollama and pull a model
ollama serve
ollama pull nomic-embed-text

# 3. Configure .cartog.toml
cat > .cartog.toml <<EOF
[embedding]
provider = "ollama"
model = "nomic-embed-text"

[embedding.ollama]
base_url = "http://localhost:11434"
EOF

# 4. Index and search — no rag setup needed
cartog index .
cartog rag index .
cartog rag search "authentication flow"

Example: Local with a different model

# Use a larger model for better quality
cat > .cartog.toml <<EOF
[embedding]
provider = "local"
model = "BAAI/bge-base-en-v1.5"
EOF

cartog rag setup     # downloads the configured model
cartog rag index .
cartog rag search "error handling"

Example: Disable re-ranking

# Skip the 1.1GB reranker model download
cat > .cartog.toml <<EOF
[reranker]
provider = "none"
EOF

cartog rag setup     # only downloads embedding model (~80MB)

cartog index <path>

Build or update the code graph. Run this first, then again after code changes.

cartog index .              # index current directory
cartog index src/           # index a subdirectory
cartog index . --force      # full re-index
cartog index . --no-lsp     # heuristic-only (~1-4s)

Incremental by default — skips unchanged files (git + SHA-256), and within changed files, uses Merkle-tree diffing to update only modified symbols.

cartog search <query>

Find symbols by partial name. Results ranked: exact match → prefix → substring.

cartog search validate                   # prefix + substring match
cartog search validate --kind function   # functions only
cartog search config --file src/db.rs    # scoped to one file
cartog search parse --limit 5            # cap results

Available --kind values: function, class, method, variable, import, interface, enum, type-alias, trait, module, document.

cartog outline <file>

Show all symbols in a file with types, signatures, and line ranges. Use this instead of reading a file when you need structure.

cartog outline src/db.rs

cartog refs <name>

All references to a symbol — calls, imports, inherits, type references.

cartog refs UserService                  # all reference types
cartog refs validate_token --kind calls  # only call sites

Available --kind values: calls, imports, inherits, references, raises, implements, type-of.

cartog callees <name>

Find what a function calls — answers "what does this depend on?".

cartog callees validate_token

cartog impact <name>

Transitive impact analysis — follows the caller chain up to N hops (default 3).

cartog impact validate_token --depth 3

Indentation shows depth. Answers "what breaks if I change this?".

cartog hierarchy <class>

Show inheritance relationships — both parents and children.

cartog hierarchy AuthService

cartog deps <file>

List symbols imported by a file — answers "what does this file depend on?".

cartog deps src/routes/auth.py

cartog stats

Summary of the index — file count, symbol count, edge resolution rate.

cartog stats

cartog doctor

Validate that all requirements are met and everything is working. Checks git repo, config, database, embedding provider, and reranker.

cartog doctor                 # check all requirements
cartog --json doctor          # structured JSON output

Each check reports OK, Warn, or Error. Exits with code 1 if any check is an error. Run this when commands fail unexpectedly or after first setup.

cartog map

Token-budget-aware codebase summary — file tree + top symbols ranked by reference count.

cartog map                    # default 4000 tokens
cartog map --tokens 2000      # compact
cartog map --tokens 8000      # detailed

cartog changes

Show symbols affected by recent git changes.

cartog changes                    # last 5 commits + working tree
cartog changes --commits 10       # last 10 commits
cartog changes --kind function    # only functions

cartog watch

Watch for file changes and auto-re-index. Keeps the graph fresh during development.

cartog watch                      # watch CWD
cartog watch src/                 # watch subdirectory
cartog watch --rag                # also auto-embed
cartog watch --rag --rag-delay 60 # embed after 60s idle
cartog watch --debounce 5         # 5s debounce window

cartog serve

Start cartog as an MCP server over stdio.

cartog serve                  # MCP server only
cartog serve --watch          # + background file watcher
cartog serve --watch --rag    # + watcher + auto RAG

cartog rag setup

Download embedding and re-ranker models from HuggingFace. Run once before using semantic search with the local provider.

cartog rag setup

Downloads ~1.2GB of ONNX models (embedding ~80MB + reranker ~1.1GB). Cached in ~/.cache/cartog/models/.

Note: When using Ollama, skip this — models are managed by the Ollama server.

# To also skip the reranker download:
[reranker]
provider = "none"

cartog rag index

Build the embedding index for semantic search. Indexes both code symbols and Markdown documents (.md files). Requires cartog index first. For the local provider, also requires cartog rag setup.

cartog rag index              # embed all symbols + documents
cartog rag index src/         # embed subdirectory
cartog rag index --force      # re-embed all

cartog rag search <query>

Semantic search — use natural language to find code by behavior or concept. Returns code only by default; use --kind document for docs or --kind all for both.

cartog rag search "validate authentication tokens"
cartog rag search "error handling" --kind function
cartog rag search "database connection" --limit 5
cartog rag search "deployment architecture" --kind document

Combines keyword (BM25/FTS5) and vector similarity, merged via RRF, then re-ranked by a cross-encoder. By default, returns code only; use --kind document for docs or --kind all for both.

Available --kind values: function, class, method, variable, import, interface, enum, type-alias, trait, module, document, all.

Agent Skill

Install cartog as an agent skill for Claude Code, Cursor, Copilot, and other compatible agents:

npx skills add jrollin/cartog

Or install manually:

cp -r skills/cartog ~/.claude/skills/

The skill teaches your AI agent when and how to use cartog — including search routing, refactoring workflows, and fallback heuristics.

Claude Plugin

For Claude Code users, the simplest setup. Run each command separately:

/plugin marketplace add jrollin/cartog

/plugin install cartog@cartog-plugins

MCP Server

cartog serve exposes 12 tools over stdio for MCP-compatible clients.

Per-Client Setup

Claude Code

claude mcp add cartog -- cartog serve --watch

Or edit ~/.claude/settings.json:

{
  "mcpServers": {
    "cartog": {
      "command": "cartog",
      "args": ["serve", "--watch"]
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cartog": {
      "command": "cartog",
      "args": ["serve"]
    }
  }
}

Cursor

Edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "cartog": {
      "command": "cartog",
      "args": ["serve"]
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "cartog": {
      "command": "cartog",
      "args": ["serve"]
    }
  }
}

OpenCode

Edit .opencode.json:

{
  "mcp": {
    "cartog": {
      "type": "stdio",
      "command": "cartog",
      "args": ["serve"]
    }
  }
}

Zed

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "cartog": {
      "command": {
        "path": "cartog",
        "args": ["serve"]
      }
    }
  }
}

Any MCP client

Point your client at cartog serve over stdio. Command: cartog, args: ["serve"].

JSON Output

All commands accept --json for structured output:

cartog --json refs validate_token
cartog refs validate_token --json    # equivalent
cartog --json stats

Token Budget

All query commands accept --tokens N to limit output:

cartog --tokens 500 search validate
cartog --tokens 200 outline src/db.rs

Uses len / 4 byte-to-token approximation. Ignored when --json is used.

Supported Languages

Performance

Indexing: 69 files / 4k LOC in 95ms (Python fixture, release build).

Edge Resolution: Heuristic vs LSP