# cartog: full index

> cartog is a code graph indexer for LLM coding agents. It parses a repository
> into a symbol graph (functions, classes, methods, imports, call edges) that an
> agent queries instead of grepping, and asks the language server to resolve each
> edge, recording which tier resolved it. Single static Rust binary, 18 languages,
> SQLite storage, 100% local: no account, no API keys, nothing leaves the machine.

Every edge carries a provenance tag, so an agent can tell a language-server fact
from a name-match guess: `lsp`, `lsp_external`, `lsp_unresolvable` (asked a real
language server), or one of six ordered heuristic tiers (`same_file`,
`import_path`, `same_dir`, `parent_scope`, `unique_global`, `kind_disambig`).
Surfaced as `provenance` in `--json` and in MCP tool output.

Search is hybrid: SQLite FTS5 keyword search plus vector KNN, merged by
reciprocal rank fusion and re-ranked by a cross-encoder, returning named symbols
with kind, signature and exact span rather than text chunks.

## Install

```
curl -fsSL https://www.cartog.dev/install.sh | sh     # macOS / Linux
cargo install cartog                                  # from source
/plugin marketplace add jrollin/cartog                # Claude Code plugin
```

Then, in a repository: `cartog init && cartog index .`

## MCP server

`cartog serve` speaks the Model Context Protocol over stdio and exposes 16 tools
(18 when the opt-in cross-project tools are enabled with `[mcp] federated = true`
or `cartog serve --federated`). `cartog ide` writes the config into installed
editors. Reference: https://www.cartog.dev/usage.html#mcp-server

## Markdown for agents

Two pages are served as plain Markdown:
https://www.cartog.dev/index.md (the project README) and https://www.cartog.dev/usage.md (the usage guide).

Those two are prose overviews. The exhaustive references — every CLI command,
every config key, every MCP tool — live in the repo and are listed under
"Reference" below; `usage.html` inlines them all if you would rather read one
page.

## Site pages

- [Landing page: what cartog is, why a graph, edge provenance, alternatives, install](https://www.cartog.dev/index.html)
- [Docs page: install, config, semantic search, MCP wiring, every CLI command, troubleshooting (the full reference, inlined)](https://www.cartog.dev/usage.html)

## Tutorials

- [install, first index, bootstrap](https://github.com/jrollin/cartog/blob/main/docs/tutorials/quickstart.md)

## How-to

- [LSP server overrides and concurrency](https://github.com/jrollin/cartog/blob/main/docs/how-to/configure-lsp-servers.md)
- [query another indexed project on this machine with `--db`](https://github.com/jrollin/cartog/blob/main/docs/how-to/query-another-project.md)
- [local ONNX, Ollama, OpenAI-compatible](https://github.com/jrollin/cartog/blob/main/docs/how-to/switch-embedding-provider.md)
- [remote push/pull via S3-compatible storage](https://github.com/jrollin/cartog/blob/main/docs/how-to/set-up-s3-sync.md)
- [upgrade, rollback, deferred updates](https://github.com/jrollin/cartog/blob/main/docs/how-to/update-cartog.md)
- [`cartog ide` and manual MCP config](https://github.com/jrollin/cartog/blob/main/docs/how-to/wire-editors.md)
- [maintainer runbook: publish the VS Code extension to the Marketplace + Open VSX](https://github.com/jrollin/cartog/blob/main/docs/how-to/publish-vscode-extension.md)

## Reference

- [all 28 commands and global flags](https://github.com/jrollin/cartog/blob/main/docs/reference/cli.md)
- [all `.cartog.toml` keys and environment variables](https://github.com/jrollin/cartog/blob/main/docs/reference/config.md)
- [16 MCP tools (+2 opt-in cross-project), progress, cancellation, logging](https://github.com/jrollin/cartog/blob/main/docs/reference/mcp-tools.md)
- [`cartog self` exit codes and state file](https://github.com/jrollin/cartog/blob/main/docs/reference/exit-codes.md)
- [full `cartog self update` surface (canonical reference; procedures are in how-to/update-cartog.md)](https://github.com/jrollin/cartog/blob/main/docs/updates.md)

## Explanation

- [design decisions, secret redaction, SQLite tuning](https://github.com/jrollin/cartog/blob/main/docs/explanation/architecture.md)
- [hybrid search, embedding models, provider architecture](https://github.com/jrollin/cartog/blob/main/docs/explanation/rag-pipeline.md)
- [three-layer change detection, Merkle invariants](https://github.com/jrollin/cartog/blob/main/docs/explanation/incremental-indexing.md)
- [rayon / tokio / std::thread models](https://github.com/jrollin/cartog/blob/main/docs/explanation/concurrency.md)
- [user-global project registry: `cartog projects`, `cartog_list_projects`, and self-populated descriptions (shipped), and the proposed later phases](https://github.com/jrollin/cartog/blob/main/docs/explanation/project-registry.md)
- [proposal — federated search and cross-service edges](https://github.com/jrollin/cartog/blob/main/docs/explanation/cross-project-queries.md)

## Background docs

- [hub: search commands, plugin, agent skill, MCP server, agents](https://github.com/jrollin/cartog/blob/main/docs/usage.md)
- [vision, target users, positioning](https://github.com/jrollin/cartog/blob/main/docs/product.md)
- [technology stack, dependencies, benchmarks](https://github.com/jrollin/cartog/blob/main/docs/tech.md)
- [workspace layout and per-crate links](https://github.com/jrollin/cartog/blob/main/docs/structure.md)
- [per-editor MCP wiring (Cursor, VS Code, Codex, Gemini, Claude Desktop, OpenCode, Windsurf, Zed, Antigravity, Kiro, Hermes)](https://github.com/jrollin/cartog/blob/main/docs/mcp-setup.md)
- [drop-in rules that teach your agent when to prefer cartog over grep](https://github.com/jrollin/cartog/blob/main/docs/agent-snippet.md)
- [Neovim, VS Code, Emacs, Zed CLI recipes](https://github.com/jrollin/cartog/blob/main/docs/editor-integration.md)
- [common errors and fixes](https://github.com/jrollin/cartog/blob/main/docs/troubleshooting.md)

## Source

- Repository: https://github.com/jrollin/cartog
- Crates: https://crates.io/crates/cartog
- License: MIT