Cartog

Install

Install script (macOS / Linux, no Rust required)

curl -fsSL https://www.cartog.dev/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 with CARTOG_INSTALL_DIR; pin a version with CARTOG_VERSION=<version> (e.g. the tag from Releases). Audit the script: site/public/install.sh.

MCP Server Setup

Fastest path: let cartog write the right config for your editor.

cartog ide                                  # all installed clients, all scopes
cartog ide --client cursor                  # one client
cartog ide --client claude-desktop --dry-run  # preview without writing

Idempotent. Existing servers in each file are preserved.

Prefer the brew/npm shape? cartog install takes editors as positional args and is always non-interactive — safer than cartog ide for scripts and agents:

cartog install cursor                 # one editor
cartog install cursor vscode codex    # several at once
cartog install                        # all detected editors
cartog install cursor --dry-run       # preview

Prefer to wire it yourself? Pick your client below.

<details> <summary><strong>Claude Code</strong> — project-scoped <code>.mcp.json</code> or user settings</summary>

One-shot:

cartog ide --client claude-code             # writes .mcp.json + user settings
claude mcp add cartog -- cartog serve --watch       # user scope
claude mcp add --scope project cartog -- cartog serve --watch

Manual (<repo>/.mcp.json):

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

Only Claude Code gets --watch by default — the others ship plain ["serve"]. Agent-driven flows churn files faster than human-driven editor flows, so the in-process file watcher pays off. Drop --watch with cartog ide --no-watch if you don't want it. </details>

<details> <summary><strong>Cursor</strong> — project <code>.cursor/mcp.json</code> or user settings</summary>

One-shot:

cartog ide --client cursor

Manual:

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

<details> <summary><strong>Codex CLI</strong> — user-only TOML at <code>~/.codex/config.toml</code></summary>

One-shot:

cartog ide --client codex

Manual:

[mcp_servers.cartog]
command = "cartog"
args = ["serve"]

Codex is user-global only. If you use cartog on multiple projects, cartog ide auto-names each section cartog-<slug>-<hash8> so they coexist. </details>

<details> <summary><strong>Windsurf</strong> — <code>~/.codeium/windsurf/mcp_config.json</code></summary>

cartog ide --client windsurf

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

<details> <summary><strong>VS Code (GitHub Copilot)</strong> — project <code>.vscode/mcp.json</code></summary>

cartog ide --client vscode

Note: VS Code's top-level key is servers (no mcp prefix):

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

<details> <summary><strong>Zed</strong> — <code>~/.config/zed/settings.json</code></summary>

cartog ide --client zed

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

<details> <summary><strong>OpenCode</strong> — <code>~/.config/opencode/opencode.json</code></summary>

cartog ide --client opencode

{
  "mcp": {
    "cartog": {
      "type": "local",
      "command": ["cartog", "serve"],
      "enabled": true
    }
  }
}

<details> <summary><strong>Gemini CLI</strong> — <code>~/.gemini/settings.json</code></summary>

cartog ide --client gemini

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

<details> <summary><strong>Claude Desktop</strong> — <code>claude_desktop_config.json</code></summary>

cartog ide --client claude-desktop

Manual (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\):

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

Restart Claude Desktop after editing. </details>

See docs/mcp-setup.md for the canonical long-form reference, including the path-naming scheme for Codex's multi-project setup, and docs/usage.md for all cartog ide flags.

Quick Start

curl -fsSL https://www.cartog.dev/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)

Semantic search (optional, still fully local)

cartog rag setup                 # download models (~1.2 GB, one-time)
cartog rag index .               # embed symbols + docs into sqlite-vec
cartog rag search "authentication token validation"

Three-tier hybrid pipeline: FTS5 keyword + vector KNN + cross-encoder re-ranking. Indexes both code (functions, classes, methods) and Markdown documents. Models run locally via ONNX Runtime — no API keys, no network calls.

Prefer Ollama or a hosted endpoint? Set provider = "ollama" or provider = "openai" (any OpenAI-compatible /v1 endpoint) in .cartog.toml. See Configuration.

Configuration

Database path is resolved automatically — no config needed for standard use:

1. --db flag / CARTOG_DB env var (highest priority)
2. .cartog.toml at git root
3. Auto git-root detection (.cartog/db.sqlite; legacy .cartog.db still read with a warning)
4. .cartog/db.sqlite in current directory

.cartog.toml (optional):

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

[embedding] provider = "ollama" # "local" (default), "ollama", or "openai" model = "nomic-embed-text"

api_key_env = "OPENAI_API_KEY" # env var NAME; never the key itself

[reranker] provider = "none" # "local" (default) or "none"

Or an OpenAI-compatible /v1 endpoint (OpenAI, Mistral, Voyage, Jina, OVHcloud,

base_url = "https://api.openai.com/v1" # swap base_url to change vendor

Agent integration: which path?

Three setup paths for agents and editors. Pick the one that matches your stack — they are alternatives, not steps.

Claude Code plugin

Run these two commands one at a time in Claude Code:

/plugin marketplace add jrollin/cartog

/plugin install cartog@cartog-plugins

First session: if the cartog binary is not already on your PATH, the plugin starts a background install and prints a one-line notice. The cartog MCP server cannot start in this first session because the binary lands after Claude Code has already tried to spawn it.

Second session: restart Claude Code. The MCP server starts, code-graph tools become available, and the SessionStart hook keeps the index fresh on every subsequent session.

Repair or upgrade: type /cartog-install at any time to install the binary synchronously (e.g. to retry a failed background install), or to upgrade an existing install to match the plugin's pinned version. The skill at skills/cartog-install/ handles both cases.

Offline / vetted install: the manual fallback is the same one used by the curl one-liner at the top of this section: download site/public/install.sh (served at https://www.cartog.dev/install.sh), inspect it, then run it.

Extra repo-root-relative globs to skip (on top of node_modules/target/vendor/...).

Troubleshooting

Full list with detailed fixes: docs/troubleshooting.md.