-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Codebase world model — maps, understands, and predicts complex software systems.
Cartograph builds a structural and historical model of any codebase. It parses source code into a dependency graph (Layer 1) and mines git history for co-change patterns and code ownership (Layer 2). The result is queryable via CLI or an MCP server, giving AI agents and humans targeted answers about code impact before making changes.
| Page | What it covers |
|---|---|
| Getting Started | Install, build, index your first repo, run your first query |
| CLI Reference | All 7 subcommands — flags, arguments, output format |
| MCP Server | Wire Cartograph into Claude Code or any MCP client; all 5 tools documented |
| Architecture | Layer 1 (structure), Layer 2 (dynamics), store schema, query engine |
| Roadmap | Planned layers 3 & 4, language parser expansion, future queries |
┌─────────────────────────────────────────┐
│ CLI / MCP │
├─────────────────────────────────────────┤
│ Query Engine │
│ blast_radius · deps · co_changes │
│ who_owns · hotspots │
├──────────────────┬──────────────────────┤
│ Layer 1: │ Layer 2: │
│ Structure │ Dynamics │
│ (tree-sitter) │ (git mining) │
├──────────────────┴──────────────────────┤
│ Store (SQLite + petgraph) │
└─────────────────────────────────────────┘
Layer 1 — Structure: tree-sitter-rust extracts module and use relationships into a directed dependency graph stored in SQLite and petgraph.
Layer 2 — Dynamics: git-log walks commit history to compute co-change frequency (files that appear together in commits) and ownership (blame-based author attribution per file).
Query Engine: graph traversals and SQL queries over the store, exposed through a unified interface to both the CLI and the MCP stdio server.
# Index a repo (run once, re-run to update)
cartograph --repo /path/to/myrepo index
# What breaks if I change this file?
cartograph --repo /path/to/myrepo blast-radius src/auth.rs
# Who should review changes to this file?
cartograph --repo /path/to/myrepo who-owns src/billing.rs
# What else tends to change alongside this file?
cartograph --repo /path/to/myrepo co-changes src/main.rs- Source: github.com/emberloom/cartograph
- License: Apache-2.0
- Part of: Emberloom — also see Emberloom Sparks, which uses Cartograph as its built-in codebase-understanding layer