# CodeCartographer [](https://github.com/HuginnIndustries/CodeCartographer/actions/workflows/ci.yml) [](LICENSE) [](https://www.npmjs.com/package/codecartographer-pi) [](package.json) > **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. ```text ● 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](docs/build-week-2026.md). --- ## 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](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) is a TUI coding agent. The CodeCartographer extension adds slash commands, a live agents widget, and the dashboard. ```bash 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: ```bash 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. ```bash npm install --global codecartographer-pi ``` Add to your host config (`~/.config/claude-code/config.json`, `claude_desktop_config.json`, etc.): ```json { "mcpServers": { "codecartographer": { "command": "codecarto-mcp" } } } ``` [Official MCP Registry listing](https://registry.modelcontextprotocol.io/?search=CodeCartographer): `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. ```bash 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 # ~/.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 /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 /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 /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: ```text 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/.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/.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](#broad-side-batch-reconnaissance) 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 ` (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 `