Three ways to install. Drop-in template, Pi-mono extension, or MCP server. Pick the one that matches your workflow.
No CLI, no runtime, no dependencies. The core is structured Markdown and YAML. Works with any LLM that can read and write files.
cp -r /path/to/CodeCartographer/.codecarto /path/to/your-repo/
Edit .codecarto/workflow/status.yaml and set the pipeline field. Defaults to the 7-phase full analysis with a split defect scan.
# Available pipeline paths: pipeline: workflow/pipeline-full-with-deep-audit.yaml # 7-phase (default) pipeline: workflow/pipeline-full-with-audit.yaml # 6-phase pipeline: workflow/pipeline.yaml # 5-phase pipeline: workflow/pipeline-defect-scan.yaml # 2-phase pipeline: workflow/pipeline-lite.yaml # 3-phase pipeline: workflow/pipeline-architecture-only.yaml # 1-phase pipeline: workflow/pipeline-synthesis.yaml # 4-phase forward synthesis (Pi/MCP only)
Read .codecarto/GUIDE.md and begin the analysis.
The LLM reads the guide, checks status.yaml for progress, and starts the next phase automatically. Each phase produces a validated output in .codecarto/findings/.
Works in Claude Code, OpenCode, Cursor, Windsurf, Aider, and any IDE copilot with file read/write access.
Install the package directly into Pi-mono. Phase sub-agents run in parallel widgets with live token tracking and file-backed session transcripts.
pi install npm:codecartographer-pi # or, from a local checkout: pi install /absolute/path/to/CodeCartographer # or, from a git URL: pi install git:github.com/HuginnIndustries/CodeCartographer
/codecarto-init
Copy .codecarto/ into the current repository and select a pipeline.
/codecarto-next
Spawn the next eligible phase as a sub-agent. Optional --llm-steer flag for customized seed prompts.
/codecarto-status
Show current phase progress and pipeline state.
/codecarto-validate
Run validation against the current phase output.
/codecarto-complete
Atomically mark a phase complete after validation passes.
/codecarto-phase
Force a specific phase even out of pipeline order.
/codecarto-skill
Run a post-pipeline skill once all phases are complete.
/codecarto-usage
Show cumulative and per-phase token usage from local phase runs.
/codecarto-open
Activate an existing workspace without resetting state.
/codecarto-vision
Run a guided product discovery interview for the synthesis pipeline.
/codecarto-switch-pipeline
Switch the active pipeline without losing findings or progress.
/codecarto-publish
Publish the reimplementation spec to a configured library.
/codecarto-library-init
Initialize a library directory with marker and config.
/codecarto-config
Show the effective merged configuration.
/codecarto-dashboard
Regenerate the dashboard HTML.
The same core primitives exposed as a Model Context Protocol server. Wire it into Claude Code, Claude Desktop, or any MCP host. The host runs the LLM, isolates phase sessions, and controls compaction; CodeCartographer returns prompts, validates outputs, and manages durable workflow state.
npm install --global codecartographer-pi
# or, in a project:
npm install codecartographer-pi
Add to your MCP host config. Claude Code uses ~/.config/claude-code/config.json; Claude Desktop uses claude_desktop_config.json.
{
"mcpServers": {
"codecartographer": {
"command": "codecarto-mcp"
}
}
}
The server exposes 18 workflow and library tools: codecarto_init,
codecarto_status, codecarto_switch_pipeline, codecarto_next,
codecarto_phase, codecarto_validate, codecarto_complete,
codecarto_skill, codecarto_publish, codecarto_library_list,
codecarto_library_reindex, codecarto_library_init,
codecarto_config, codecarto_vision, codecarto_open,
codecarto_usage, codecarto_dashboard, and codecarto_list_skills.
Workflow tools accept an absolute cwd for the target repository; library tools
accept a configured or explicit library path.
The synthesis pipeline runs through Pi or MCP. It combines a product vision with reusable, versioned reimplementation specs, pauses for explicit human selection, preserves conflicts, and produces work packages with a decision-level provenance ledger.
/codecarto-init synthesis
# Fill .codecarto/inputs/vision.md
/codecarto-next --auto
The first run creates a ranked proposal, completes that phase, and then intentionally stops at the confirmation preflight.
# In proposal.md:
| [x] | event-router | v2 | ... |
/codecarto-next --auto
Merge and finalization read only the checked, version-pinned specs. An unknown entry or version is rejected before any LLM phase starts.
This site is plain HTML, CSS, and JavaScript. GitHub Pages serves the repository's
main branch from the repository root at codecarto.dev.
main.npm test against the authoritative CodeCartographer checkout and wait for the pull-request checks to pass.main at /(root).CNAME set to codecarto.dev. GitHub Pages manages the approved TLS certificate and enforces HTTPS.https://codecarto.dev/ and hard refresh.CodeCartographer reads your source code multiple times across phases and produces thousands of words of structured output. The fixed template overhead is about 27,000 tokens across a 6-phase run. Source code reading is the dominant variable cost.
A full 5-phase run costs roughly $2 to $4 in API fees. Larger codebases scale linearly. Start with architecture-only to test output quality before committing.
Use one session per phase for fresh context windows. The lite pipeline gives 80% of the value for understanding. Skip the defect scan on weaker models.