<div align="center">

Cartograph

Cartograph 3.0 — current code intelligence, stored with your project.

Native Rust CLI and MCP server · per-project RocksDB · code-aware BM25 · typed code graph

Quick start · Agent workflow · Languages · Architecture · Documentation · Changelog

</div>

---

Cartograph turns a source checkout into a searchable, immutable-generation code graph. It gives coding agents compact evidence about declarations, references, call flow, change impact, affected tests, and source freshness through one native CLI and the Model Context Protocol.

The source checkout remains the source of truth. Every evidence packet carries generation provenance, freshness, confidence, truncation, and explicit abstention instead of presenting stale or incomplete data as certainty.

[!IMPORTANT] Version 3.0 replaces PostgreSQL with embedded RocksDB. Each project owns its database, and a persistent native service keeps its graph current. Existing v2 projects need a source rebuild and host restart; see Upgrade.

Start here

| I want to… | Go to | | --- | --- | | Install Cartograph and build a first graph | Quick start | | Hand setup to a coding agent | Agent-assisted installation | | Connect Codex, Claude Code, Cursor, or another host | MCP usage | | Look up a command, flag, or JSON field | CLI reference | | Check a language, extension, or framework | Language support matrix | | Inspect and maintain native storage | Storage and operations | | Fix a failed setup, error code, or stale graph | Troubleshooting | | See what changed in each release | Changelog | | Browse every guide by task | Documentation home |

What Cartograph gives an agent

| Question | Evidence | | --- | --- | | Where is this declared or referenced? | Exact symbol, path, reference, and identifier lookup | | Which code is most relevant? | Code-aware BM25 over names, implementation identifiers, and documentation | | What calls this, and what does it call? | Typed callers, callees, imports, references, and shortest paths | | What could this change affect? | Bounded reverse impact and structurally connected tests | | Where is numerical behavior risky or statically unknown? | Generation-scoped Rust operation/hazard/precision sites with exact spans and explicit evidence limits | | Is the graph current? | Immutable generation identity and exact supported-source freshness | | What changed in the working tree? | Separately labeled live overlay and Git-ref review packets | | Is an LLM required? | No for exact, lexical, graph, review, freshness, or affected-test workflows |

Cartograph also supports standard SCIP export, persistent per-file SCIP overlays, model-scoped semantic retrieval, generated artifacts with explicit provenance, and deterministic task-intent routing.

Quick start

[!TIP] Prefer agent-assisted setup? Give your coding agent the copy-paste task in Agent-assisted installation.

1. Install the native executable

macOS (Apple Silicon, macOS 26+) or Linux (ARM64/x64, glibc 2.41+):

curl -fsSL https://raw.githubusercontent.com/adder-factory/cartograph/main/install.sh | sh
cartograph --version

Windows (x64), in PowerShell:

irm https://raw.githubusercontent.com/adder-factory/cartograph/main/install.ps1 | iex
cartograph --version

The installer verifies the archive against the release's SHA256SUMS. To build from source, use the pinned Rust toolchain, a C/C++ compiler, and libclang:

cargo build --locked --release -p cartograph-cli

2. Build the first graph

cd /path/to/project
cartograph index .
cartograph doctor . --format json
cartograph status . --format json
cartograph context 'explain the primary request flow' --project-path .

Each project owns .cartograph/data; no server or Docker bootstrap is needed. An unchanged second index skips publication. Require a fresh generation and real retrieval evidence before calling setup ready. Doctor reports native capabilities separately from freshness, models, registration, and transport.

For a previously indexed PostgreSQL project, run cartograph db migrate --to rocksdb --project-path . to rebuild and verify the native destination while preserving legacy data. See the migration guide for the scope of that rebuild.

3. Connect a coding agent

Cartograph writes project-scoped MCP configuration and pins the absolute native executable path. For Claude Code the project entry lives under projects.<path>.mcpServers in ~/.claude.json, Claude's local scope.

cartograph install --yes --target codex  --location local --project-path .  # OpenAI Codex
cartograph install --yes --target claude --location local --project-path .  # Claude Code
cartograph install --yes --target cursor --location local --project-path .  # Cursor

The installer supports 19 hosts in total; see the CLI reference for every target ID.

4. Verify the live integration

A setup is ready only after all four signals pass:

1. cartograph doctor proves database capabilities.
2. cartograph index publishes one complete generation.
3. cartograph status reports that generation as fresh.
4. A real find or context query returns generation-scoped evidence.

A CLI request proves the executable and database path. After restarting an agent host, make one live MCP request as the separate transport-health check. Until that happens, doctor deliberately reports liveTransport as not_checked; an on-disk registration never proves which child process an already-running host loaded.

Keep the graph current

On macOS, start a project service that stays alive when an MCP client disconnects:

cartograph service start --project-path . --format json
cartograph service status --project-path . --format json

Filesystem events use a 150 ms quiet window and incremental file parsing. Continuous edits are coalesced for at most two seconds, and a periodic source check catches missed events. These are scheduling bounds; end-to-end freshness also includes extraction, publication, and the query. Check autoSync and generation freshness instead of assuming every repository updates in a second. On Linux, run cartograph watch --project-path . under your user service manager, or in the foreground. Automatic service registration currently uses macOS launchd. On Windows, the serving MCP primary owns the watcher.

Upgrade

For an existing v2 installation, install v3 with the installer above, then run the v3 executable:

cartograph db migrate --to rocksdb --project-path . --format json
cartograph upgrade --apply --project-path . --json

Migration rebuilds the graph from current source and verifies retrieval before recording completion. It preserves the old PostgreSQL database. Legacy notes, sessions, embeddings, and artifacts are not imported; keep the old data if you need them. The upgrade repairs recognized host pins and reports any remaining manual steps. Reopen attached coding hosts to load v3, then verify live MCP status and a real query. Future native upgrades use the same upgrade --apply command after stopping the existing owner. For a macOS native service:

cartograph service stop --project-path . --format json
cartograph upgrade --apply --project-path . --json
cartograph service start --project-path . --format json
cartograph status . --format json

For a manually managed owner, stop that project's watch or serving process cooperatively, upgrade, then start it again through its service manager. Start the new owner before reconnecting MCP hosts. Verify the status report's version as well as the client's --version; a new client can still proxy to an older owner. See the migration guide.

Platform and database support

RocksDB is compiled into the Rust executable on macOS, Linux, and Windows. One primary owns each project's database. macOS/Linux clients can reuse a running MCP owner through private same-user Unix IPC. Windows currently requires closing the existing primary before another process opens that project. PostgreSQL connection flags and managed-container operations are retired.

See storage operations for concurrency, maintenance, source-rebuild migration, and current capacity limits.

Agent workflow

A reliable coding loop starts with freshness, narrows with structural evidence, and closes with impact-aware verification:

cartograph status .                                              # 1. is the graph fresh?
cartograph context 'fix authentication token validation' --project-path .   # 2. task evidence
cartograph find 'validateToken' --by name --project-path .       # 3. exact anchor
cartograph graph <symbol-id> --direction impact --project-path . # 4. blast radius
cartograph affected --symbol-id <symbol-id> --project-path .     # 5. tests to run
cartograph review --ref main --project-path .                    # 6. review the diff

If status is stale, run cartograph index . or use the bounded MCP admin action. Indexing unchanged source is a no-op; changed source publishes a complete new generation atomically.

Core MCP tools

| Tool | Purpose | | --- | --- | | cartograph_status | Current generation, counts, capability readiness, and freshness | | cartograph_find | Exact name/path/reference lookup or code-aware BM25 | | cartograph_context | Intent-aware evidence, graph context, and edit candidates | | cartograph_entry_points | Routes, commands, MCP tools, exports, and API boundaries | | cartograph_graph | Callers, callees, reverse impact, paths, and symbol similarity | | cartograph_affected | Bounded affected-test selection | | cartograph_numerical | Generation-scoped static numerical hazards, coverage, explanations, and non-executing probe plans | | cartograph_review | Git-ref plus staged, unstaged, and untracked evidence | | cartograph_admin | Explicit index, sync, embedding, and maintenance jobs |

MCP profiles are coding, core, full, read-only, and review. Profiles are immutable authorization ceilings with deterministic tool lists; a narrower profile cannot call hidden tools. Cartograph supports modern stateless MCP 2026-07-28 plus the legacy 2024-11-05 initialize path. Modern hosts should cache the stable complete catalog and dynamically place only task-relevant schemas in the model context; the server does not mutate tools per connection. See MCP usage.

<details> <summary>CLI surface — selected high-use forms</summary>

These are selected high-use forms, not the complete command inventory. Run cartograph --help for the installed binary or see the CLI reference for every top-level command.

cartograph index [PROJECT]
cartograph status [PROJECT]
cartograph find <QUERY> --by auto|name|content|env|sql|build|path|refere