A tour of every piece: pipeline variants, evidence classification, phase-gating, cross-session continuity, and the output artifacts you end up with.
Seven analysis variants scale from quick orientation to a deep audit behind a Broad-Side scout brief. The forward synthesis pipeline combines a vision with confirmed reusable specs to create a traceable project plan.
7 phases
Complete analysis with a two-pass defect scan. An early mechanical sweep catches surface-level issues; a later semantic pass re-examines defects with full contracts and protocols context before reimplementation planning.
The default pipeline. Best when you need the deepest defect analysis grounded in full behavioral understanding.
Two directions: analysis distills source code into reusable specifications; synthesis combines human-confirmed specifications with a product vision and preserves decision-level provenance in the resulting plan.
Six single-turn analysis lenses — architecture, API surface, security, mechanical defects, conventions, porting — fire at any git repository as asynchronous jobs on the OpenRouter Batch API at roughly half of synchronous pricing. No workspace required. The output is a cross-lens executive report and a P0–P3 triage work order of unverified leads — a map of where the expensive interactive run should spend its attention, never evidence on its own.
Submit estimates the run from file sizes against live per-model pricing and refuses anything over max_cost. The Pi command shows the per-lens breakdown and asks — approval is the force flag; the MCP tool refuses until the caller passes force. The API key comes from OPENROUTER_API_KEY or config.yaml, never from a command argument.
Zero-config slicing collapses small repositories into one request and splits large ones by directory. Truncated results re-submit once with a doubled output cap. Lens batches poll concurrently. Incremental re-scouting diffs against the previous run's git HEAD and rescans only changed modules.
Defect and convention prompts adapt to the repository's language (Go, Python, Rust, TypeScript/JavaScript, or a neutral default), and lens_models routes individual lenses to a stronger batch model where it pays — security and defects — while the cheap default carries the rest.
Every finding is an unverified scouting signal. The scout-first pipeline routes leads into the interactive phases, and each phase must confirm them against source, dismiss them with a reason, or carry them forward — none may be reported on the brief's authority.
Two surfaces: /codecarto-broadside on the Pi extension and the codecarto_broadside MCP tool — same submit, collect, status, and models actions, same guardrails, byte-identical lens prompts.
An LLM can sound certain about things it inferred. CodeCartographer requires every finding to carry an evidence tag so you know what was observed, what was deduced, and what remains an open question.
Directly visible in source code or documentation. Not inferred.
Deduced from patterns and structure. High confidence but not directly stated.
Behavior or assumption that may not survive a rewrite or language change.
About a system the code only calls — a server, engine, driver, API. Unverifiable by reading this source; needs a runtime probe.
Could not determine from available sources. Needs human input or deeper analysis.
If an LLM cannot classify a finding with one of these five tags, the finding is not specific enough to be useful. Vague assertions get rejected by the validation protocol — and the evidence level bounds the action: an external-behavior claim or open question can never carry a settled fix action. Validation reads the findings tables and fails a defect report that pairs them.
Each phase produces a structured output against a template. The validation protocol checks
completion criteria: are all required sections present, are findings tagged with evidence
levels, are open questions logged in status.yaml.
templates/
Structured Markdown templates enforce consistent sections across projects and sessions. Every artifact has the same shape regardless of which LLM produced it.
VALIDATE.md
Run after every phase. Checks that outputs match templates, evidence tags are applied, and partial results are logged properly before allowing the status to advance.
CodeCartographer does not ask one context window to remember the entire investigation. Each phase turns a large body of source evidence into a smaller, more task-specific artifact that downstream phases can read and validate.
Evidence-tagged distillation
This is deliberate distillation, not incidental chat summarization. Templates, evidence labels, open questions, and validation gates reduce the risk of an unsupported claim becoming “fact” as information moves downstream.
Each phase gets a fresh context window and re-reads the upstream findings declared by the pipeline. Progress, open questions, carry-forward items, decisions, and closeouts live under .codecarto/ rather than only in the conversation.
Compaction inside one oversized phase can still be lossy. When full coverage will not fit, the phase records PARTIAL validation and routes unresolved work through open_questions or carry_forward instead of hiding the gap.
Practical result: compacting or replacing the orchestrator session does not erase pipeline progress. The next host session can reopen the durable state and continue; Pi users run /codecarto-open to attach without resetting it.
Large codebases need multiple sessions. status.yaml is the single source of
truth. After the host opens the workspace, the new session reads the guide, checks the status
file, sees what is complete, and starts the next eligible phase. No explaining what happened before.
status.yamlMutable per-project state. Tracks phase completion, current phase, open questions, carry-forward work, and the active pipeline.
THREAD_LOG.mdAppend-only index pointing to per-session closeout files. Durable findings stay in phase outputs and closeouts; the log gives new sessions a compact route into that evidence without becoming a second summary store.
In the Pi extension, /codecarto-open safely activates existing state in a fresh
orchestrator session. Phase sub-agents persist transcripts alongside that session.
/resume, /tree, and /export browse them as
first-class sessions with lineage back to the orchestrator.
It is better described as progressive, evidence-tagged distillation. Each phase produces a purpose-built artifact with templates, evidence levels, known unknowns, and a validation gate before downstream phases use it.
Cross-phase state is reconstructed from files under .codecarto/, so compacting or replacing the orchestrator does not erase progress. Pi phase compaction now uses a phase-aware continuation summary, writes scratch/checkpoints/<phase>.md, and records compaction outcomes in local usage telemetry. The summary is still lossy, so material gaps remain explicit as PARTIAL, open_questions, or carry_forward.
The Pi extension automatically runs phases in isolated, file-backed sessions and applies phase-aware compaction only to sessions named CodeCartographer phase: <id>. An MCP host controls its own LLM sessions and compaction, so it should dispatch one fresh session per phase. The MCP server itself does not run an agent.
Drop-in mode uses the same durable files and phase protocol, but isolation is procedural rather than enforced. Start each phase in a fresh session, read the declared upstream artifacts, and preserve unresolved work on disk.
No. The porting bundle is the final intentional compression boundary. Its source index carries load-bearing claims, defect dispositions, coverage gaps, and deep-read triggers. Final synthesis opens lower-level findings only for a named gap, conflict, missing acceptance detail, or defect rationale.
Every phase has a Coverage and limits section naming inspected scope, skipped scope, evidence basis, and blind spots. Material gaps produce PARTIAL validation and remain visible in open_questions or carry_forward.
No — by design. Batch reconnaissance output is explicitly unverified scouting signal from a single-turn model with no filesystem access. It steers attention; the interactive phases (or a human) confirm every lead against source before it becomes a finding.
Each artifact targets a different audience: engineers, reviewers, maintainers, and the next LLM session.
Layers, public surfaces, runtime lifecycle, dependency direction, porting priorities.
Multi-pass scan: logic, error handling, concurrency, security, API drift, config risks.
User-visible behavior, defaults, side effects, error modes, black-box acceptance checks.
Events, state machines, persistence notes, compatibility hazards, internal message flow.
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.
Broad-Side executive synthesis and P0–P3 triage work order — unverified leads for the interactive phases to confirm.
Read the installation docs for drop-in setup, Pi extension commands, or MCP server configuration.