CodeCartographer turns "explain this repo" into a staged investigation. Architecture, defect scan, behavioral contracts, protocol notes, porting synthesis, and a reimplementation spec. Each finding is evidence-tagged so confidence stays visible.
Use the Pi extension for the best UX, the MCP server for other coding agents, or the drop-in template when you want a zero-runtime evaluation. Each phase builds on the last.
Start with the system map. Then move into defects, contracts, and protocols with the architecture already pinned down. Each phase validates before the next one starts.
Findings are marked as observed fact, strong inference, portability hazard, or open question. You know what is certain and what is a guess.
status.yaml tracks progress. A fresh LLM session reads it and resumes the next phase automatically. No explaining what happened last time.
Layers, dependency direction, public surfaces, runtime lifecycle, concurrency model.
Multi-pass scan for logic errors, security issues, concurrency bugs, API violations.
Feature-by-feature behavior with defaults, error handling, and acceptance tests.
Event flows, state machines, persistence formats, compatibility hazards.
Synthesis layer ranking what matters, what is risky, what needs special treatment in a rewrite.
Language-agnostic build plan with modules, acceptance scenarios, and known unknowns.
The default run is a 7-phase full analysis with a split defect scan. Scale back when you only need orientation, behavior recovery, or defect hunting.
The default. Two-pass defect scan with contracts/protocols context between passes. Complete reimplementation readiness.
Single defect scan. Cheaper than the deep variant when defects are mostly mechanical.
Porting and reimplementation without any defect scan. Best when the rewrite matters more than the audit.
Architecture map plus multi-pass defect audit. Maintenance triage without porting plans.
Architecture, contracts, protocols. The fastest option that still leaves durable product knowledge.
Quick structural overview. Low-cost first pass to orient yourself before committing to deeper analysis.
Fastest path: install the Pi extension or copy .codecarto/ into your
repository. The workflow reads the status file, picks up the next phase, and starts
writing structured findings.
# Copy the template into your repo cp -r /path/to/CodeCartographer/.codecarto /path/to/your-repo/ # Point any LLM at the guide Read .codecarto/GUIDE.md and begin the analysis.
Built as a Pi-mono extension with slash commands, widgets, and tool gating. Also ships as an MCP server. The core template stays dependency-free for any file-aware agent.
Install the package and use /codecarto-init, /codecarto-next, /codecarto-status, and more. Phase sub-agents run in parallel widgets with live token tracking.
Seven tools mirroring the Pi commands. Wire it into Claude Code, Claude Desktop, or any MCP-compatible host. Byte-identical prompts across surfaces.
Copy .codecarto/ into any repo. Works in OpenCode, Cursor, Windsurf, Aider, and any IDE copilot with file read/write access.
Tour the pipeline variants, read the installation docs, or download the repository and drop it into your next project.