CodeCartographer

CodeCartographer

Understand an unfamiliar codebase with an AI agent — and get a validated spec you can rebuild from. CodeCartographer turns a repository into layered architecture, behavioral contracts, defect findings, and a language-agnostic reimplementation spec, with each phase validated before the next one runs. Works with Pi, Claude Code, Cursor, Codex, or any MCP-capable agent.

●  CodeCartographer

├─ ✓ architecture phase ⟳ 25 · 76 tool uses · 1.0M tokens · 4m28s ├─ ✓ defect-scan-mech. ⟳ 39 · 91 tool uses · 2.4M tokens · 7m05s └─ ⠹ contracts phase ⟳ 11 · 37 tool uses · 335.1k tokens · 40.1s ⎿ extracting behavioral contracts from server/index.ts…

---

Why CodeCartographer

Asking an LLM to "analyze this repo" loses context halfway through, hallucinates findings, and leaves no artifact the next session can pick up. CodeCartographer fixes three things:

1. The filesystem is the memory, not the conversation. Each phase writes a smaller, templated, evidence-tagged artifact to .codecarto/findings/. Later phases re-read the specific upstream files they need. A new session — or a context compaction — picks up from status.yaml without losing progress.

1. Every phase attests to its own completion, and the gate holds it to that. Each output ends with a ## Validation table where the phase marks every completion criterion PASS, PARTIAL, or FAIL with evidence. Validation parses that table, cross-checks the findings' evidence/action pairing and the declared secondary outputs, and refuses to advance on a FAIL, a missing output, or a verdict it cannot read. It does not re-judge the criteria itself — that is the model's honest self-assessment plus two mechanical checks, which is exactly what a later phase can hold the earlier one to.

1. The output is a spec, not a chat log. The final reimplementation-spec.md is language-agnostic, module-inventoried, and carries acceptance scenarios plus known unknowns. Hand it to another agent to rebuild from.

Every finding is tagged with an evidence level: observed fact, strong inference, portability hazard, external-behavior claim, or open question.

---

At a glance

Publish completed reimplementation specs from Pi or MCP, then run the synthesis pipeline to turn a product vision and explicitly confirmed library entries into a conflict-aware project-plan.md with a decision-level provenance ledger.

If CodeCartographer saves you a day of codebase archaeology, star the repo — it helps the next person find it.

OpenAI Build Week reviewers: see the new-vs-existing scope and one-command demo.

---

Install

Three surfaces, in recommended order. All three share the same core/ and produce byte-identical phase prompts. Pi provides the richest orchestration UX; Pi and MCP both support the executable library and synthesis workflows; drop-in mode provides the analysis framework without those runtime operations.

1. Pi extension — recommended for interactive use. First-class UX.
2. MCP server — for Claude Code, Codex, opencode, Cursor, Claude Desktop, and any other MCP-capable agent.
3. Drop-in template — pure .codecarto/ markdown + YAML for one-off evaluation or any LLM that can read and write files. Library and synthesis workflows are not available in pure drop-in mode; the analysis side works fully.

Pi extension (recommended)

Pi is a TUI coding agent. The CodeCartographer extension adds slash commands, a live agents widget, and the dashboard.

pi install npm:codecartographer-pi          # from the npm registry

pi install /absolute/path/to/CodeCartographer # from a local checkout pi install git:github.com/HuginnIndustries/CodeCartographer # from a git URL

Don't run npm install codecartographer-pi for the Pi use case. Plain npm install puts the package on disk but doesn't register it with Pi. Use pi install npm:... so Pi writes the package into its own ~/.pi/agent/settings.json.

For extension development, point Pi directly at the entrypoint:

pi -e /absolute/path/to/CodeCartographer/extensions/codecarto/index.ts

MCP server (for other coding agents)

Use this when your coding agent isn't Pi — Claude Code, Codex, opencode, Cursor, Claude Desktop, or anything else that speaks MCP. The host drives the conversation and runs the LLM; CodeCartographer provides phase prompts, validation, and experimental library publish/list/reindex operations.

30-second setup for Claude Code, Cursor, Codex, and Claude Desktop: see the [MCP quickstart](docs/mcp-quickstart.md).

Teaching an agent to drive it: call the codecarto_guide tool — the server returns the full drive loop, the phase-handoff contract, executor selection, and recovery patterns, with nothing to install. The same content ships as an installable skill at agent-skill/codecartographer/ for agents that load skills from disk, and /codecarto-guide [topic] reads it into a Pi session.

npm install --global codecartographer-pi

Add to your host config (~/.config/claude-code/config.json, claude_desktop_config.json, etc.):

{

"mcpServers": { "codecartographer": { "command": "codecarto-mcp" } } }

Official MCP Registry listing: io.github.HuginnIndustries/codecartographer.

Drop-in template (one-off / evaluation)

Use this to try CodeCartographer in any repo without installing anything, or in environments where neither Pi nor an MCP-capable agent is available. Works with any LLM that can read and write files.

cp -r /path/to/CodeCartographer/.codecarto /path/to/your-repo/

Then in the LLM session: Read .codecarto/GUIDE.md and begin the analysis.

Limitation. Drop-in mode runs the analysis pipeline fully, but library + synthesis workflows require executable code through Pi or MCP.

---

Forward synthesis quickstart

Analysis turns repositories into reusable specifications. Synthesis runs the other direction: it combines a raw product vision with human-confirmed specifications and produces an implementation-ready plan without losing provenance.

1. Configure the library that contains specs published with /codecarto-publish or the MCP codecarto_publish tool:

   # ~/.codecarto/config.yaml or .codecarto/workflow/config.yaml

library: path: /absolute/path/to/codecarto-library namespace: your-namespace # omit for a single-tenant library publish_confirm: true # Pi asks before writing; MCP refuses a publish that lacks confirm: true

1. Initialize a clean planning workspace and fill in its brief:

   /codecarto-init synthesis

Edit .codecarto/inputs/vision.md with the audience, problem, desired outcome, constraints, and non-goals.

1. Run until CodeCartographer creates the candidate proposal:

   /codecarto-next --auto

The run intentionally stops before merging. Review .codecarto/findings/goal-synthesis/proposal.md and change one or more candidate boxes from [ ] to [x].

1. Resume:

   /codecarto-next --auto

The final .codecarto/findings/goal-synthesis/project-plan.md contains product scope, architecture, work packages, acceptance gates, an unresolved-conflict register, and a provenance ledger mapping every load-bearing decision back to the vision or a confirmed specification. Runtime preflight checks prevent merging or finalization before explicit human confirmation.

---

How it works

The "code" is structured Markdown + YAML inside .codecarto/:

• `GUIDE.md` — LLM entry point. Every session reads this first.
• `workflow/pipeline.yaml` — phase definitions, dependencies, output paths.
• `workflow/status.yaml` — mutable per-project state. Single source of truth for progress.
• `workflow/VALIDATE.md` — validation protocol run after every phase.
• `findings/ /SKILL.md` — detailed analysis instructions per phase.
• `templates/` — output templates that enforce consistent structure.

Phases form a DAG: contracts and protocols can run in parallel after architecture; porting waits for both; reimplementation-spec is last. The host (Pi, MCP, or your shell) reads the active pipeline, finds the next phase whose dependencies are all complete, hands the LLM that phase's instructions, validates the output, and advances status.yaml.

For multi-session work, every new session reads .codecarto/GUIDE.md (or the lighter NEW_THREAD_BLURB.md), checks workflow/status.yaml, and picks up where the last session left off. You don't explain what happened in previous sessions.

---

Progressive distillation and context resilience

CodeCartographer is a progressive, evidence-tagged distillation of a codebase. It does not ask one context window to retain the entire investigation. Instead, each phase turns a large body of source evidence into a smaller, more task-specific artifact that the next phase can read:

source code

→ architecture map → behavioral contracts + protocols + defect findings → porting bundle → reimplementation spec

This is deliberate distillation, not incidental chat summarization. Each artifact follows a template, preserves evidence levels and known unknowns, and must pass validation before it becomes an input to downstream phases.

What happens when conversation context is compacted?

The filesystem, not the conversation, is the durable memory of a run:

• Each phase gets a fresh context window. In the Pi extension it runs as an isolated phase sub-agent; MCP and drop-in hosts should use the same one-session-per-phase pattern.
• Completed findings live under .codecarto/findings/. Later phases re-read the specific upstream artifacts declared by the active pipeline instead of relying on conversational recall.
• workflow/status.yaml records progress, terminal open_questions, in-pipeli