cartographer

---

The Problem

You understand a codebase by building a mental model — not of files, but of behaviors: what happens when a user signs up, how payments flow, where things can fail. That model lives only in your head. It's rebuilt from scratch every time. It can't be shared, inspected, or queried.

Cartographer externalizes that model.

It gives Claude Code a persistent memory of your codebase's behaviors and structure — grounded in source evidence, navigable as a map, and accessible to engineers and non-engineers alike.

What It Does

You: "explore this codebase"

Claude traces the system's key behaviors end-to-end.
Entities emerge from the flows — not from directory structure.
Boundaries form around concerns that break together.

The map shows what the system DOES, not how files are organized.
Each fact links back to the exact source code that proves it.

Open localhost:3847 to see the map.
Click a boundary to zoom in (semantic zoom).
Select a behavior flow to see the path light up.
Ask Claude questions — answers cite the stored model.

Getting Started

Prerequisites

• Node.js 20+
• Claude Code CLI

Install via Plugin Marketplace

/plugin marketplace add miltonian/cartographer
/plugin install cartographer@cartographer

Install from Source

git clone https://github.com/miltonian/cartographer.git
cd cartographer
npm install
npm run build:ui
claude --plugin-dir ./plugin

Use

/cartographer explore          # Deep autonomous exploration
/cartographer analyze          # Guided analysis (or focused: analyze auth)
/cartographer review-pr 123    # Overlay a PR on the map
/cartographer map              # Open browser UI
/cartographer status           # Model statistics
/cartographer snapshot         # Save a backup
/cartographer restore <file>   # Restore from backup
/cartographer reset            # Start fresh

How It Works

Three Pieces

┌──────────────────────────┐
│  Claude Code + Plugin    │  Agent. Traces behaviors, records findings.
│          │ MCP (stdio)   │
├──────────┼───────────────┤
│  Local Service           │  Backbone. Stores world-model, serves API.
│          │ HTTP + WS     │
├──────────┼───────────────┤
│  Browser UI              │  Map. Renders projections, navigable depth.
└──────────────────────────┘

Behavior-First Analysis

Cartographer leads with what happens, not what exists. The agent:

1. Identifies the system's key behaviors ("what are the most important things this system does?")
2. Traces each behavior end-to-end through the code
3. Records entities as they're encountered along the flow
4. Lets boundaries emerge from which entities cluster together

Structure comes from behavior, not from directories.

The Ontology

Entity Kind	What It Represents
boundary	A concern — things that break together
capability	Something the system can do
actor	Where external intent enters
entity	State that persists or transforms
side-effect	Observable consequence outside the boundary
invariant	A rule that must hold true
failure-point	Where the system can fail

Evidence, Not Hallucination

Every fact carries source evidence with confidence levels:

Confidence	Meaning
proven	Directly observed in source code
high	One inference step from observed facts
medium	Synthesized from multiple observations
low	Educated guess
speculative	Hypothesis, not yet verified

The map visually distinguishes all levels. You always know what's proven vs. inferred.

Behavior Flows

Flows are the primary unit of understanding — a named path through the system:

Customer checkout:
  Cart validation → Payment processing → Order creation → Confirmation email

Select a flow in the UI panel to see it highlighted on the map. Each step is numbered. Non-participating nodes dim.

Perspectives

Multiple angles on the same codebase. A perspective is a named lens — a subset of entities in focus.

• Default — everything (the satellite view)
• Agent-created — focused on a concern ("auth", "data pipeline")
• Boundary-derived — created by semantic zoom (clicking into a boundary)

Each perspective has its own layout. Open multiple browser tabs with different perspectives via URL params.

Semantic Zoom