Cartograph

Cartograph

Generation-safe code intelligence for AI coding agents.

Native Rust CLI and MCP server · PostgreSQL 18 · code-aware BM25 · typed code graph

[](https://github.com/adder-factory/cartograph/releases/latest) [](https://github.com/adder-factory/cartograph/actions/workflows/v2-rust.yml) [](LICENSE) [](https://www.rust-lang.org/)

[Quick start](#quick-start) · [Agent workflow](#agent-workflow) · [Large codebases](#large-codebases-and-streaming-indexing) · [Architecture](#architecture) · [Documentation](#documentation)

---

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] > Cartograph v2 is PostgreSQL-only. It requires PostgreSQL 18.4 or newer within > major version 18, ParadeDB pg_search 0.25.2, and pgvector 0.8.4 or newer > (0.8.6 recommended for external PostgreSQL). > There is no SQLite runtime, compatibility mode, importer, optional feature, > or fallback.

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

1. Install the native executable

macOS and Linux:

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

Windows PowerShell:

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

The installers select the native archive for the host, verify it against the release SHA256SUMS, and place cartograph on the user PATH.

2. Build the first graph

On macOS or Linux with a local Docker daemon:

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

db start creates project-owned, loopback-only resources and pulls the pinned upstream ParadeDB image. doctor fails closed unless PostgreSQL, pg_search, pgvector, preload, BM25, migrations, and code tokenization all pass. doctor --json retains ready as the backward-compatible hard-capability result and mirrors it as capabilitiesReady. Its separate projectReadiness object reports database, index, freshness, deterministic retrieval, optional semantic retrieval, on-disk registration, live MCP transport, and overall onboarding states. Checks that doctor does not perform are not_checked, never inferred from another successful layer; nextActions contains only path-safe follow-up commands.

3. Connect a coding agent

Cartograph writes only project-local MCP configuration and pins the absolute native executable path:

# OpenAI Codex
cartograph install --yes --target codex --location local --project-path .

# Claude Code
cartograph install --yes --target claude --location local --project-path .

# Cursor
cartograph install --yes --target cursor --location local --project-path .

If the default managed database port is occupied, pass the selected port to both db start --port and install --managed-database-port . The installer writes that non-secret loopback port into the portable serve arguments for the selected host. Direct project commands discover an existing project-owned container's published port when neither the flag nor CARTOGRAPH_MANAGED_DATABASE_PORT is set; an explicit wrong port fails with the discovered port instead of a generic connection error.

Versioned native installs register the stable ~/.cartograph-cli/current/bin/cartograph launcher. A normal version-to-version upgrade is one resumable command from the project root:

cartograph upgrade --apply --project-path .

It checksum-verifies and smoke-tests the release, switches the stable launcher, applies safe append-only schema migrations, refreshes the current generation, runs doctor, verifies a fresh next-process status, and repairs stale owned Codex, Claude, and Cursor pins. The only routine manual boundary is closing and reopening an already-running agent host, which cannot hot-load a replaced MCP child. If an older managed container itself must be replaced, the command stops with the exact backup and confirmation commands; rerun the same upgrade command afterward to resume rather than restarting the workflow. A cold first-time image pull has its own 15-minute budget; a timeout is reported as retryable and never treated as evidence that the container is incompatible. A fully idempotent rerun does not request another host reopen unless that invocation changed the binary or repaired a host pin. The confirmed database replacement also resumes an interruption after the old container was stopped and renamed but before the new candidate was created; do not rename its rollback slot manually.

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.

> [!TIP] > Prefer agent-assisted setup? Give your coding agent the task in > [Agent-assisted installation](docs/AGENT-INSTALL.md).

Platform and database support

| Host | Native release | Managed local database | External PostgreSQL | | --- | ---: | ---: | ---: | | macOS 26 on Apple Silicon | Yes | Yes, with local Docker | Yes | | Current 64-bit Linux, glibc 2.41+ (arm64 / x64) | Yes | Yes, with local Docker | Yes | | Windows 11 25H2+ / Server 2025 x64 | Yes | Not enabled | Yes |

Only current 64-bit operating-system generations are release targets. Intel macOS and every 32-bit architecture are unsupported. Linux release binaries target Debian 13's glibc 2.41 baseline or newer. Every Linux archive is built in a pinned Rust/Trixie container and executed in a separate pinned Debian 13 runtime container before publication.

For an external deployment, the database administrator installs PostgreSQL 18.4 or newer within major version 18, pg_search 0.25.2, and pgvector 0.8.4 or newer, and creates pgvector before pg_search. Load the connection URL from the shell or a secret manager rather than a committed file:

export CARTOGRAPH_DATABASE_SCHEMA='cartograph_project'
# CARTOGRAPH_DATABASE_URL must already be present in the environment.

cartograph doctor /absolute/path/to/project
cartograph index /absolute/path/to/project
cartograph status /absolute/path/to/project

Database URLs are secrets. Public errors, debug output, MCP responses, archives, and project records are required to omit credentials and absolute checkout paths. See [PostgreSQL storage and operations](docs/STORAGE-BACKENDS.md).

Agent workflow

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

cartograph status .
cartograph context 'fix authentication token validation' --project-path .
cartograph find 'validateToken' --by name --project-path .
cartograph graph  --direction impact --project-path .
cartograph affected --symbol-id  --project-path .
cartograph review --ref main --project-path .

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](docs/MCP-USAGE.md#modern-protocol-and-dynamic-tool-selection).

CLI surface

These are selected high-use forms, not the complete command inventory. Run cartograph --help for the installed binary or see the [CLI reference](docs/CLI-REFERENCE.md) for every top-level command.

cartograph index [PROJECT]
cartograph status [PROJECT]
cartograph find  --by auto|name|content|env|sql|build|path|reference|bm25|hybrid
cartograph context  [--exact-name NAME] [--exact-path PATH] [--exact-reference TEXT]
cartograph entry-points [--bucket public-exports] [--limit 20]
cartograph graph  --direction callers|callees|both|impact
cartograph graph  --direction path --to 
cartograph graph  --direction similar --k 5 --min-score 0.3
cartograph affected [CHANGED_FILE ...] --max-nodes 40
cartograph affected --symbol-id  --max-nodes 40
cartograph review --ref 
cartograph serve --mcp [--profile coding|core|full|read-only|review]
cartograph doctor [PROJECT]
cartograph db 
cartograph install --yes --target 
cartograph uninstall --yes --target 

Text output is optimized for concise human diagnostics. JSON is the stable automation surface where exposed by command help.

Large codebases and streaming indexing

No special command is required for a large first index. With the default generationStorage: "auto", Cartograph selects its PostgreSQL spill path at 64 Cargo manifests, 10,000 supported files, 64 MiB of indexed source, or when a conservative 16x source-expansion estimate reaches maxGenerationBytes. A dense smaller corpus can opt in explicitly through .cartograph/config.json:

{
  "version": 2,
  "generationStorage": "postgres"
}

The spill path lazily admits at most 64 files and 64 MiB of combined source per parse work item, reuses one parser per encountered language, and writes file-local extraction plus resolved typed facts in bounded batches. PostgreSQL then performs deterministic partitioned reduction behind the staging generation's lease and fence. Readers continue to see the prior complete generation until the new canonical generation passes validation and publishes.

This bounds the bulky per-file working set; it does not make every native structure unlimited. Compact project-wide resolution, clone, and centrality indexes remain bounded by maxGenerationBytes, while maxSpillBytes and maxSpillRows bound the durable unordered payload. Cartograph fails closed at either boundary rather than lowering extraction or graph quality.

Parse time and complete-index time are separate measurements. The published [VS Code streaming benchmark](docs/v2/benchmarks/LARGE-PUBLIC-CORPUS-STREAMING.md) records the final pre-release candidate retained with v2.1.11; it is not an exact tagged-binary rerun. That candidate extracted 14,693 files / 171,015,058 source bytes in 23.04 seconds. The full cold request, including resolution, reduction, exact digest, BM25 construction, and atomic publication, completed in 467.42 seconds at 2.90 GiB maximum RSS. An unchanged-source reconciliation took 3.19 seconds. A qualified error such as resolve_progress_stalled means the watchdog observed no durable work checkpoint; it does not merely mean that a large stage ran for a long time.

See [configuration](docs/CONFIGURATION.md), [performance tuning](docs/PERF-TUNING.md), and [capacity troubleshooting](docs/TROUBLESHOOTING.md#native-generation-reaches-its-capacity-bound) for the complete limits and operator guidance.

Architecture

flowchart LR
    A[Source checkout] --> B[Bounded Rust discovery]
    B --> C{Generation storage selector}
    C -->|memory| D[Parallel parse and memory reduction]
    C -->|PostgreSQL spill| E[Lazy parse batches and fenced staging rows]
    E --> F[Deterministic partitioned reduction]
    D --> G[Canonical facts]
    F --> G
    G --> H[(PostgreSQL 18 canonical generation)]
    H --> I[ParadeDB BM25]
    H --> J[Typed graph and impact]
    H --> K[Optional pgvector semantic retrieval]
    I --> L[Evidence packet]
    J --> L
    K --> L
    L --> M[Native CLI]
    L --> N[MCP server]

The architecture has a few hard boundaries:

• Native runtime: Rust owns discovery, parsing, resolution, bounded parallel

indexing, retrieval, CLI, and MCP. No Bun, Node.js, or TypeScript runtime is shipped.

• One durable store: PostgreSQL 18 owns canonical project and generation

state. ParadeDB BM25 and model-scoped HNSW are rebuildable derived indexes.

• Atomic publication: incomplete or unhealthy generations never become

current. Readers query one verified immutable generation. Large builds can use generation-fenced PostgreSQL spill and deterministic partitioned reduction without exposing staging rows.

• Deterministic concurrency: 1, 2, 4, 8, and 16-worker builds reduce to the

same logical digest and ordered evidence.

• Optional generation: exact lookup, BM25, graph, review, freshness, and

affected tests work without an LLM. Generative output cannot replace structural truth.

For crate ownership, schemas, leases, retrieval, MCP boundaries, and failure semantics, read the [v2 architecture](docs/v2/ARCHITECTURE.md).

Language support

The stable registry production-admits 130 language modes and the complete 163 v1 extension manifest, plus additive Python .pyi support. Sixty-four modes use pinned native tree-sitter grammars; 66 mixed-markup, configuration, domain-specific, and game-scripting modes use bounded Rust structural scanners.

Every admitted mode must

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: adder-factory
• Source: adder-factory/cartograph
• License: MIT

Install and usage instructions live in the source repository linked above.