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.

2. 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.

3. 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.

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:

   yaml

   Copy

   # ~/.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
   

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

   text

   Copy

   /codecarto-init synthesis
   

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

3. Run until CodeCartographer creates the candidate proposal:

   text

   Copy

   /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].

4. Resume:

   text

   Copy

   /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/: