DiagramPilot is a local-first, repo-native diagram compiler for AI coding agents. It validates structured DiagramSpec source files, renders review-stable SVG or PNG artifacts, and exports Mermaid, D2, or DOT text from the same source of truth. Agents use DiagramPilot to create, update, validate, and render software architecture diagrams directly inside a repository.
DiagramPilot Source Files are YAML-only. The CLI supports local agent authoring
loops with create, inspect, format, lint, watch, configured outputs,
fixed Output Profiles, SVG/PNG rendering, and Mermaid/D2/DOT export. Local MCP
clients can add the optional @diagrampilot/mcp adapter package.
Public documentation is hosted at https://diagrampilot.com.
- Codebase architecture diagrams that stay reviewable in Git.
- Dependency and module maps generated from one structured source file.
- Service interaction diagrams for runtime, data, and integration flows.
- AI-maintained documentation that needs stable, repairable source.
- Pull request architecture reviews backed by
checkand generated artifacts. - Repo-native diagram artifacts committed beside the source they came from.
Install, run, or remove the package:
Use the canonical Agent Authoring Loop:
Start with the Checkout Demo Project:
- Checkout demo quickstart
- Demo source file:
demo-projects/checkout/docs/architecture.dp.yaml - Demo SVG artifact:
demo-projects/checkout/docs/architecture.svg
Compare DiagramPilot with adjacent tools and wire it into automation:
Run the primary workflow from the repository root:
cd demo-projects/checkout
diagrampilot check
diagrampilot inspect
diagrampilot icons search database
diagrampilot create docs/new-architecture.dp.yaml --template architecture
diagrampilot create docs/system-context.dp.yaml --template system-context
diagrampilot create docs/service-map.dp.yaml --template service-map
diagrampilot validate docs/architecture.dp.yaml
diagrampilot lint docs/architecture.dp.yaml
diagrampilot format docs/architecture.dp.yaml
diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
diagrampilot render docs/architecture.dp.yaml --view runtime --out docs/architecture-runtime.svg
diagrampilot render docs/architecture.dp.yaml --format png --out docs/architecture.png
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml
diagrampilot import docs/legacy.d2 --format d2 --out docs/imported-d2.dp.yaml
diagrampilot import docs/legacy.dot --format dot --out docs/imported-dot.dp.yaml
diagrampilot export docs/architecture.dp.yaml --format mermaid
diagrampilot export docs/architecture.dp.yaml --view runtime --format mermaid --out docs/architecture-runtime.mmd
diagrampilot export docs/architecture.dp.yaml --format d2 --out docs/architecture.d2
diagrampilot export docs/architecture.dp.yaml --format dot --out docs/architecture.dotUse check as the read-only repo review/CI command. Use inspect when an
agent needs a read-only inventory of DiagramPilot Source Files, topology,
Stable IDs, and artifact expectations before editing. Use create when a repo
needs a starter *.dp.yaml source from the maintained architecture, flow,
package-map, system-context, or service-map templates. Use validate
when you need explicit source repair output. Use lint when you need
readability warnings for one valid source before rendering or review. Use
format to rewrite a valid DiagramPilot Source File into canonical YAML before
review. render requires --out, defaults to SVG, and supports
--format svg|png; PNG rendering rasterizes the SVG render path. Add
--view <view-id> to render or export a declared projection from the same
DiagramPilot Source File. export prints to stdout by default and writes only
when --out is provided.
Use icons list and icons search <query> to discover packaged lucide:*
icon references for nodes and groups.
- Follow the Agent workflow guide for
the canonical create, format, validate, inspect
--json, render, and check loop. - Inspect the repository first with
diagrampilot inspectordiagrampilot inspect --json. - Edit only
*.dp.yamlDiagramPilot Source Files. - Preserve Stable IDs when labels, descriptions, or grouping change.
- Run
diagrampilot formatanddiagrampilot validatebefore rendering. - Run
diagrampilot lintfor review readability warnings on larger diagrams. - Run
diagrampilot renderordiagrampilot generateto refresh Derived Artifacts. - Run
diagrampilot checkbefore committing diagram changes. - Never hand-edit generated artifacts such as SVG, PNG, Mermaid, D2, DOT, or Markdown embed outputs.
DiagramPilot source files store DiagramSpec as YAML:
*.dp.yaml
Agents should update DiagramPilot source files and regenerate outputs rather than hand-editing generated artifacts. Rendered SVG artifacts include deterministic provenance metadata with the source path, source SHA-256 hash, DiagramPilot version, and renderer version.
*.dp.json is not a DiagramPilot Source File path. Repo discovery ignores JSON
source files, explicit commands reject non-YAML source paths generically, and
DiagramPilot does not provide a JSON-to-YAML migration command. JSON remains
supported for --json CLI output, the DiagramSpec JSON Schema, SVG provenance
metadata, package manifests, and other tooling surfaces.
diagrampilot format <path> parses and validates one *.dp.yaml source before
rewriting it in canonical YAML key order. Formatting preserves DiagramSpec data,
unknown metadata, and object/array order. It does not promise comment
preservation; YAML comments may be removed or moved during formatting.
Mermaid, D2, and DOT are text formats for diagram interoperability.
DiagramPilot is an agent-safe compiler and workflow for maintaining
DiagramSpec source, validating it locally, rendering review-stable artifacts,
and exporting text diagrams when those formats are the right downstream
target. diagrampilot import <input> --format mermaid|d2|dot --out <path> is
a best-effort adoption helper: it writes a new valid *.dp.yaml, refuses
overwrite unless --force is present, and reports preserved, approximated,
and dropped constructs in text or JSON.
DiagramPilot is available under the MIT Code License.
Canonical DiagramPilot Brand Assets live in assets/brand/:
diagrampilot init
diagrampilot init --docs
diagrampilot init --config
diagrampilot create docs/architecture.dp.yaml --template architecture
diagrampilot create docs/system-context.dp.yaml --template system-context
diagrampilot create docs/service-map.dp.yaml --template service-map
diagrampilot check
diagrampilot inspect
diagrampilot generate
diagrampilot watch docs
diagrampilot icons list
diagrampilot icons search database
diagrampilot check docs --json
diagrampilot inspect docs --json
diagrampilot validate docs/architecture.dp.yaml
diagrampilot validate docs/architecture.dp.yaml --json
diagrampilot fix docs/architecture.dp.yaml --json
diagrampilot fix docs/architecture.dp.yaml --fallback-icon lucide:database
diagrampilot lint docs/architecture.dp.yaml
diagrampilot lint docs/architecture.dp.yaml --json
diagrampilot format docs/architecture.dp.yaml
diagrampilot render docs/architecture.dp.yaml --out docs/architecture.svg
diagrampilot render docs/architecture.dp.yaml --view runtime --out docs/architecture-runtime.svg
diagrampilot render docs/architecture.dp.yaml --format png --out docs/architecture.png
diagrampilot import docs/legacy.mmd --format mermaid --out docs/imported.dp.yaml
diagrampilot import docs/legacy.d2 --format d2 --out docs/imported-d2.dp.yaml
diagrampilot import docs/legacy.dot --format dot --out docs/imported-dot.dp.yaml
diagrampilot export docs/architecture.dp.yaml --format mermaid
diagrampilot export docs/architecture.dp.yaml --view runtime --format mermaid --out docs/architecture-runtime.mmd
diagrampilot export docs/architecture.dp.yaml --format d2 --out docs/architecture.d2
diagrampilot export docs/architecture.dp.yaml --format dot --out docs/architecture.dotinit does not create local agent docs or Repo Workflow Configuration by
default. Use init --docs only when the repository wants managed llms.txt
and docs/diagrampilot.md guidance. Use init --config to create a minimal
diagrampilot.config.yaml; rerunning it fails with repair guidance if the
config already exists.
create <path> --template architecture|flow|package-map|system-context|service-map
writes a valid starter DiagramPilot Source File, refuses to overwrite an
existing file, and prints the next validate and SVG render --out commands.
check discovers DiagramPilot source files in the current directory, one
explicit directory, or one explicit source file. It validates them and checks
expected artifacts without writing files. Without config it checks
next-to-source same-stem Expected SVG Artifacts through DiagramPilot provenance
metadata.
inspect discovers DiagramPilot source files and reports title, direction,
Diagram Object counts, Stable IDs by object type, topology roots/depth, and
artifact expectations. inspect --json emits the same read-only inventory for
agents, including invalid-source diagnostics and stale or missing artifact
summaries when practical.
lint <path> validates one DiagramPilot Source File and reports readability
warnings without writing files. lint differs from validate, which reports
source correctness errors, and check, which verifies expected Derived
Artifact freshness. Initial warnings cover orphan nodes, unlabeled edges,
missing edge kinds, duplicate node or group labels, groups with more than 12
direct objects, nodes with more than 6 incoming or outgoing edges, diagrams
with more than 50 objects, and diagrams over 1.5 edges per node once they have
at least 20 nodes.
fix <path> plans and applies only deterministic source repairs. Use
fix <path> --json as the no-write planning mode. Mutation mode writes only
the DiagramPilot Source File after post-fix validation succeeds. The first
repair set covers canonical formatting and unknown Lucide icon replacement
only when a packaged fallback is supplied with --fallback-icon lucide:<name>.
Optional diagrampilot.config.yaml is discovered upward from the command
scope, validated before source processing, reported in --json output, and can
use sources.ignore for source discovery plus artifacts mappings for
configured SVG, PNG, Mermaid, D2, DOT, and Markdown expectations. Configured
Mermaid, D2, and DOT use content freshness; configured PNG freshness is
presence-only.
Configured outputs can opt into fixed output profiles with profile: clean,
profile: compact, profile: overview, or profile: presentation.
overview keeps topology while suppressing edge labels for dense review
artifacts. Profiles live only in diagrampilot.config.yaml; DiagramSpec source
files should not carry styling fields, CSS, custom themes, or per-object
presentation choices.
Configured Markdown outputs are standalone generated embed files. They link to
configured artifacts in the same mapping with paths relative to the embed file,
and check marks an embed stale when the embed or a referenced artifact is
missing, unreadable, unchecked, or not fresh. diagrampilot generate [path]
rewrites configured Derived Artifacts and generated Markdown embed files for an
explicit scope.
diagrampilot watch [path] runs a local authoring loop for an explicit scope.
It watches *.dp.yaml and diagrampilot.config.yaml, debounces changes, runs
repo workflow checks first, and generates only when the source/config state is
valid.
The Model Context Protocol stdio server lives in the optional
@diagrampilot/mcp package. Install it only for local MCP clients and launch
the dedicated diagrampilot-mcp executable. Keeping MCP out of the core
diagrampilot package keeps CLI/CI installs smaller, lowers the default
runtime dependency surface, and lets the MCP adapter iterate independently.
See the MCP guide.
icons list prints packaged lucide:* icon references in stable order.
icons search <query> searches packaged Lucide names locally and prints
matching lucide:* references, one per line.
- Public documentation
- Agent workflow guide
- Installation and removal guide
- Checkout demo quickstart
- MCP guide
- Icon reference
- Comparisons and adjacent tools
- Integrations and agent recipes
- DiagramSpec v1 JSON Schema
npm packages: