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-scout-first.yaml # 8-phase deep audit behind a Broad-Side scout brief 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.
/codecarto-broadside
Batch reconnaissance: submit, collect, status, models. Prices the run per lens and asks before spending.
/codecarto-list-skills
List the post-pipeline skills, plus the ungated Broad-Side reading guide.
/codecarto-guide
Read a topic of the packaged agent guide into the session; tab-completes the topics.
/codecarto-refresh-scaffold
Refresh the framework-owned files from the packaged template after a confirm; project state untouched.
/codecarto-amend
Apply a post-pipeline amendment after a preview confirm — the only compliant way to close a question once the pipeline is complete.
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 22 workflow, library, and reconnaissance tools: codecarto_init,
codecarto_open, codecarto_vision, codecarto_status,
codecarto_switch_pipeline, codecarto_next,
codecarto_phase, codecarto_validate, codecarto_complete,
codecarto_skill, codecarto_list_skills, codecarto_guide,
codecarto_amend, codecarto_refresh_scaffold,
codecarto_publish, codecarto_library_init, codecarto_library_list,
codecarto_library_reindex, codecarto_config,
codecarto_usage, codecarto_dashboard, and codecarto_broadside.
Workflow tools accept an absolute cwd for the target repository; library tools
accept a configured or explicit library path.
Broad-Side fires six analysis lenses at any git repository as asynchronous OpenRouter Batch API
jobs — roughly half of synchronous pricing, no workspace required. Submit prices the run per
lens and refuses anything over max_cost; results land in
.codecarto/broadside/ as an executive synthesis and a P0–P3 triage work order of
unverified leads. The scout-first pipeline distills them into a brief every
interactive phase must account for.
codecarto_broadside {cwd, action: "submit"}
codecarto_broadside {cwd, action: "collect"}
Refuses a run over max_cost until the caller passes force: true. Also: status and models (the batch-model catalog with live pricing).
/codecarto-broadside submit /codecarto-broadside collect
Shows the per-lens cost breakdown and asks — approval is the force flag. Live per-lens progress while batches poll.
The OpenRouter key comes from OPENROUTER_API_KEY or .codecarto/broadside/config.yaml — never from a command argument, which would land it in the session transcript. Findings are unverified scouting leads, never evidence.
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 Broad-Side scout pass over a medium repository typically costs cents at batch pricing and tells the expensive run where to look.
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.