Skip to content

Getting Started

Jump to bottom
Stas edited this page Mar 15, 2026 · 1 revision

Getting Started

Prerequisites

  • Rust (stable toolchain) — install via rustup
  • Git — must be on $PATH; used by the historian layer to walk commit history

No external database required. Cartograph stores everything in a single SQLite file.

Install

From source (recommended)

git clone https://github.com/emberloom/cartograph.git
cd cartograph
cargo build --release

The binary is at target/release/cartograph. Add it to your $PATH or invoke it with cargo run --release -- during development.

Run without installing

cargo run --release -- --repo /path/to/your/repo <subcommand>

Step 1 — Index a repository

Before any query, run index to build the database:

cartograph --repo /path/to/myrepo index

Output:

Indexing /path/to/myrepo...
  Structure: done
  Git history: 412 commits
  Co-changes: 873 pairs
  Ownership: done
Index complete.

The index is stored at .cartograph/db.sqlite inside the target repo by default. Re-run index any time to refresh it after new commits.

Custom database path:

cartograph --repo /path/to/myrepo --db /tmp/myrepo.sqlite index

Step 2 — Query

All queries require --repo to point at the same repo you indexed. The --db path defaults to .cartograph/db.sqlite within that repo.

Blast radius

What does changing this file affect?

cartograph --repo /path/to/myrepo blast-radius src/main.rs
ENTITY                                   DEPTH      EDGE
------------------------------------------------------------
src/lib.rs                               1          imports
src/store/mod.rs                         1          imports
src/query/mod.rs                         2          imports

Dependencies

What does this file import? What imports it?

# Downstream: what does src/lib.rs depend on?
cartograph --repo /path/to/myrepo deps src/lib.rs

# Upstream: what depends on src/lib.rs?
cartograph --repo /path/to/myrepo deps src/lib.rs --direction upstream

Co-changes

What tends to change alongside this file?

cartograph --repo /path/to/myrepo co-changes src/store/graph.rs
ENTITY                                   CONFIDENCE
-------------------------------------------------------
src/store/schema.rs                      1.00
src/query/blast_radius.rs                0.62

Confidence is normalized — 1.0 means the most frequently co-changed pair in the entire repo.

Ownership

Who last touched this file?

cartograph --repo /path/to/myrepo who-owns src/historian/mod.rs
OWNER                          CONFIDENCE
---------------------------------------------
alice@example.com              1.00
bob@example.com                0.40

Hotspots

Which files have the most connections — highest blast radius surface area?

cartograph --repo /path/to/myrepo hotspots
ENTITY                                   CONNECTIONS
-------------------------------------------------------
src/store/graph.rs                       24
src/lib.rs                               18
src/main.rs                              14

Step 3 — MCP server (optional)

To use Cartograph as a tool from Claude Code or another MCP client, run the serve subcommand and wire it up in your MCP config. See the MCP Server page for setup instructions.

Updating the index

Re-run index after new commits. Entities are upserted — it is safe to re-index at any time:

cartograph --repo /path/to/myrepo index

Troubleshooting

Git history: skipped — The target repo has no git history, or git is not on $PATH. Layer 2 (co-changes, ownership) requires a git repo with at least one commit.

Entity not found: src/foo.rs — The file path must match exactly what was indexed. Try running hotspots to see what entities are in the database, then match the path format shown there.

Stale results — Re-run index to refresh the database after new commits or file renames.

Clone this wiki locally