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

What you get	Where it lives
Layered analysis pipeline — architecture → defect scan → behavioral contracts → protocols → porting → reimplementation spec	.codecarto/ template
Validation gates between phases — the phase's own ## Validation table plus two cross-checks; no advancing past a FAIL	core/ state machine
Three surfaces, one framework — Pi extension (recommended), MCP server (for other coding agents), or drop-in template (one-off / evaluation)	All three share core/
Live progress widget while phase sub-agents work	Pi extension
HTML dashboard — single-file aggregate of progress, links, usage, narrative	.codecarto/dashboard.html
Per-phase token tracking	/codecarto-usage
Opt-in LLM steering of the next phase's seed prompt	/codecarto-next --llm-steer
Forward synthesis — vision + confirmed library specs → provenance-backed project plan	pipeline-synthesis.yaml

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:

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

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

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

   /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/<phase>/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-pipeline carry_forward, and a separate post_pipeline backlog for optional spikes, amendments, deltas, decisions, and reruns after completion. Phase agents propose changes in .codecarto/scratch/handoffs/<phase>.yaml; completion validates and applies them under a lock with host timestamps, one canonical closeout, and an idempotent THREAD_LOG.md entry.
• Pi phase transcripts are file-backed and remain available through /resume, /tree, and /export, even when the active model context has been compacted.
• For isolated Pi phase sessions, compaction uses a phase-aware continuation summary that explicitly preserves evidence, files inspected, output progress, open questions, and validation gaps. The resulting summary is also checkpointed atomically at .codecarto/scratch/checkpoints/<phase>.md.
• Pi records successful, failed, and aborted compactions plus their trigger (threshold, overflow, or manual) in local usage data and exposes the totals in the widget, /codecarto-usage, completion summaries, and dashboard.

As a result, compaction—or even replacement—of the orchestrator session does not erase pipeline progress. A new session can reconstruct the relevant state from disk and continue.

The remaining limit is within a single oversized phase. Even Pi's phase-aware summary is still a lossy distillation, and MCP/drop-in compaction remains entirely host-controlled. Phase instructions therefore prioritize targeted reads, durable checkpoints, and explicit coverage accounting; if full coverage will not fit, the phase records PARTIAL validation and places unresolved work in open_questions or carry_forward. Cross-phase context loss is largely designed out; intra-phase context pressure is observed and bounded rather than hidden.

The porting bundle is the final intentional compression boundary. It carries a source index, load-bearing invariants, defect dispositions, and deep-read triggers. reimplementation-spec reads that bundle by default and opens lower-level reports only for a named gap, conflict, missing acceptance detail, or defect rationale.

---

Phases produce these artifacts

Artifact	Description
Architecture map	Layers, dependency direction, public surfaces, runtime lifecycle, concurrency model
Defect report	Multi-pass scan for logic errors, security issues, concurrency bugs, API violations
Defect fix tracker	Remediation log mapping each fix, deferral, or acceptance back to the defect report
Behavioral contracts	Feature-by-feature behavior with defaults, error handling, and acceptance tests
Protocols and state	Event flows, state machines, persistence formats, compatibility hazards
Porting bundle	Everything synthesized into a porting-oriented view with priority rankings
Reimplementation spec	Language-agnostic build plan with modules, acceptance scenarios, and known unknowns

Every finding is tagged with an evidence level: observed fact, strong inference, portability hazard, external-behavior claim, or open question. Every phase output ends with the phase's own validation table against the pipeline's completion criteria, and the gate reads that table before the pipeline advances.

---

Pipeline variants

The default is a 7-phase run that splits the defect scan into a mechanical early pass and a semantic late pass — the reimplementation phase then designs around defects with full contracts and protocols context. Scale back if you want less:

Variant	Phases	Use when
Full with deep audit (default)	7	Complete analysis with split defect scan; reimplementation grounded in contracts/protocols-aware defect findings
Scout first	8	The deep-audit run preceded by a broadside-scout phase that distills an existing Broad-Side run into a routing brief every later phase reads
Full with audit	6	Single early defect scan; cheaper than the deep variant when defects are mostly mechanical
Full	5	Porting or reimplementation without any defect scan
Defect scan	2	Maintenance audit to surface latent problems
Lite	3	You need to understand behavior without porting plans
Architecture only	1	Quick structural overview
Synthesis	4	Turn a product vision and confirmed library specifications into a provenance-backed implementation plan

Switch the active pipeline with /codecarto-switch-pipeline <variant> (Pi) or codecarto_switch_pipeline (MCP). This rewrites status.yaml in-place without deleting findings, handoffs, usage data, or closeouts. Phases that exist in both the old and new pipelines preserve their completion status, and the cursor lands on the next phase the new pipeline still needs. A carry-forward whose target phase the new pipeline does not run moves to post_pipeline (the switch names each one), where an amendment can close it.

On disk:

Variant	Pipeline file
Full with deep audit (default)	workflow/pipeline-full-with-deep-audit.yaml
Scout first	workflow/pipeline-scout-first.yaml
Full with audit	workflow/pipeline-full-with-audit.yaml
Full	workflow/pipeline.yaml
Defect scan	workflow/pipeline-defect-scan.yaml
Lite	workflow/pipeline-lite.yaml
Architecture only	workflow/pipeline-architecture-only.yaml
Synthesis	workflow/pipeline-synthesis.yaml

---

The dashboard

Every state change re-renders .codecarto/dashboard.html — a self-contained single-file artifact you open in any browser. Aggregates everything a human wants to see at a glance:

• Pipeline progress strip with per-phase status badges
• Per-phase cards with output links, open questions, carry-forward routing, owner notes, last-run usage
• Aggregate token and compaction telemetry + per-phase breakdown
• Activity timeline of phase runs (tokens, duration, compactions)
• Open questions roll-up grouped by source phase
• Closeouts list (reverse-chronological) with relative-path links

No external assets of any kind — nothing linked, nothing fetched. The file inlines two <script> blocks of its own (a JSON data island and the search/filter code), so it works opened directly from file://. Light/dark via prefers-color-scheme.

Opt-in narrative summary. /codecarto-dashboard --narrate runs the orchestrator's model as a one-shot session that writes a 200–400 word executive summary citing specific findings from recent closeouts. Cached to .codecarto/.dashboard-narration.local.md and preserved across deterministic re-renders with a "(N runs since)" staleness note.

---

Pi extension features

Beyond the slash commands, the Pi extension layers on:

Phase sub-agents. /codecarto-next spawns each phase as an isolated AgentSession. Tool calls, file reads, and reasoning live in the child's own context window — they never accumulate in the orchestrator. Your TUI stays on the orchestrator session and remains responsive while phases work in background.

Live agents widget above the editor showing tool count, token usage, elapsed time, and current activity.

●  CodeCartographer
└─ ⠹  architecture phase  ⟳ 3 · 5 tool uses · 12.3k tokens · 1m32s
       ⎿ reading…

File-backed phase sessions. Phase transcripts persist to the same Pi session directory the orchestrator uses, so /resume, /tree, and /export browse them as first-class sessions. Each appears as CodeCartographer phase: <id> with lineage back to the orchestrator's session.

Phase-aware compaction and checkpoints. Only isolated sessions named CodeCartographer phase: <id> receive the specialized compaction prompt. It preserves the phase goal, evidence, inspected files, output progress, open questions, and validation gaps, then writes the resulting summary to .codecarto/scratch/checkpoints/<phase>.md. Orchestrator and unrelated Pi sessions retain normal host compaction.

Phase-completion summary in the orchestrator transcript. When a phase finishes, a Markdown closeout block is appended to the orchestrator's session via pi.sendMessage(...). Visible in the TUI scrollback; available to the orchestrator's LLM as context on your next message. No auto-trigger — you stay in control.

Opt-in LLM-steered seed prompts. Set orchestrator.llm_steer_next_phase: true in .codecarto/workflow/config.yaml (or pass --llm-steer per invocation), and the orchestrator's LLM rewrites the next phase's seed prompt to highlight relevant prior findings. Off by default — extra orchestrator-side tokens, opt-in. The rewritten prompt is injected into the orchestrator transcript so you can audit what the rewriter chose to emphasize.

Per-phase usage tracking. Each phase run is appended to .codecarto/workflow/.usage.local.yaml. /codecarto-usage reports cumulative + per-phase token, runtime, tool-use, and compaction totals, including threshold/overflow/manual triggers and successful/failed/aborted outcomes.

Tool interception. bash is blocked outright; edit and write are confined to .codecarto/, plus the configured, marker-validated CodeCartographer library when one is configured. Phase sub-agents get the same hook over a narrower root — .codecarto/ alone, since a phase writes findings and handoffs and never publishes.

Slash commands