Evidence before geometry
Important nodes and edges trace back to code, contracts, runtime observations, or an explicit requirement.
source-linked claims
AI-native engineering visualization
Make the system visible before you change it.
Diago is an open-source MCP toolkit for software architecture diagrams in Codex and Claude Code. Turn code, tasks, and conversations into interactive diagrams with evidence you can review.
- Codex + Claudeone plugin contract
- 8 diagram typesone question per view
- 7 native MCP toolscatalog to renderer
Swipe or use arrow keys to pan the diagram.
A better engineering artifact
Not another pretty box-and-arrow picture.
The toolkit gives agents a rigorous path from source evidence to a visual that can survive architecture review.
One question per view
Eight focused engineering views each answer the question their layout is built to explain.
decision-focused scope
Uncertainty stays visible
Facts, assumptions, and recommendations remain distinct instead of collapsing into one confident-looking diagram.
honest semantics
Choose by question
Eight views. Zero guesswork.
Start with the engineering decision. The advisor selects the smallest view that can explain it.
Architecture
What exists, who owns it, and how the boundaries connect.
components · dependencies
Sequence
What happens over time between callers, services, and providers.
calls · retries · responses
Workflow
Which steps, decisions, approvals, and failure paths control the work.
branches · owners · exits
Dataflow
Where data begins, transforms, moves, and persists.
sources · lineage · stores
Lifecycle
How an entity changes state and which guards allow each transition.
states · triggers · recovery
Data model
Which entities, fields, constraints, and relationships define the domain.
entities · keys · cardinality
Timeline
Which engineering milestones occur and how phases depend on one another.
milestones · phases · dependencies
Layers
Where responsibilities, abstractions, controls, and defenses are enforced.
layers · controls · gaps
One durable contract
Plan once. Render, review, and evolve.
A small JSON plan keeps the agent, renderer, and reviewer aligned. The interactive HTML remains a delivery artifact—not the source of truth.
- ✓ Source-grounded claims
- ✓ Explicit scope boundaries
- ✓ Standalone HTML output
- ✓ Mobile and accessibility gates
{
"schemaVersion": 2,
"task": "Add idempotent checkout",
"source": { "kind": "repository" },
"selection": {
"renderer": "architecture",
"profile": "feature-context"
},
"evidence": {
"facts": ["contract: idempotency-key"],
"assumptions": ["reservation expires"],
"recommendations": ["persist replay result"]
},
"complexity": { "detail": "balanced" },
"fidelity": { "omitted": [] }
}schema v2 excerptcomplete examples in reposhowcase ✓
Evidence workflows · new in v0.7.0
Inspect independent sources together.
Plan source inspections and dependent cross-checks before authoring a diagram. Available in Diago v0.7.0 through the plugin’s MCP tool and the CLI.
Follow dependencies
The planner identifies ready tasks within a concurrency limit. A completed branch can unlock its next task while unrelated work continues.
Contain failures
Keep successful source reports when another task fails. Track elapsed time, retry only eligible failures, and stop at the attempt budget.
Keep conflicts visible
Preserve citations and separate supported, unverified, and contradicted reports. Conflicting claims stay out of diagram-plan facts.
node bin/diago.mjs evidence examples/checkout.evidence-workflow.json --jsonThe host performs inspections, verifies claims, and stops timed-out workers. Diago evaluates the supplied snapshot and returns the next eligible work; it does not launch agents or independently prove claims.
Start in a minute
One repository. Your agent of choice.
Install the complete plugin, connect the standard local stdio MCP server directly, or use the deterministic CLI on its own. No cluster or remote endpoint is required.
01
Install the Codex marketplace
Add the GitHub repository as a marketplace, then install the plugin with its skills and MCP tools.
codex plugin marketplace add amirtaherkhani/diago
codex plugin add diago@diago
TRY IT
Use $diago-engineering-diagram to visualize this feature from API entry point to persistence.
After installation
Describe the decision. Diago builds the view.
Start a new agent thread in the repository you want to explain. Ask Diago to inspect the source, choose the smallest useful diagram, keep assumptions visible, and render a reviewable HTML artifact.
CodexUse $diago-engineering-diagram to…
Claude Code/diago:diago-engineering-diagram
01
Feature architecture
Map a feature end to end
Use $diago-engineering-diagram to map this feature from its API entry point to persistence. Inspect the code, separate facts from assumptions, and render architecture and sequence views.
02
Design pattern
Explain whether a pattern fits
Use $diago-engineering-diagram to evaluate whether the Strategy pattern fits this task. Show the current coupling, proposed objects, tradeoffs, and where the pattern should not be used.
03
Best-practice workflow
Plan a safer rollout
Use $diago-engineering-diagram to find the safest workflow for rolling out this schema change. Show owners, validation gates, failure paths, rollback steps, and the evidence for each recommendation.
04
Diagram review
Check a diagram against code
Use $diago-review-diagram to audit this diagram against the repository. List unsupported claims, missing boundaries, ambiguous edges, and visual issues, then recommend focused corrections.
05
Incident investigation
Trace a failure across services
Use $diago-engineering-diagram to trace this timeout from the incoming request through every service and dependency. Ground the sequence in code and runtime evidence, then show retry, timeout, and failure paths.
06
Data flow
Follow sensitive data
Use $diago-engineering-diagram to follow customer data from collection to deletion. Show trust boundaries, transformations, stores, external processors, retention rules, and any unverified privacy assumptions.
07
Entity lifecycle
Make state changes explicit
Use $diago-engineering-diagram to explain the payment lifecycle. Map every state, transition trigger, guard, terminal outcome, timeout, and recovery path, and link verified behavior to its source.
08
Refactoring plan
Extract a boundary safely
Use $diago-engineering-diagram to plan extracting this module into a service. Compare current and proposed boundaries, dependencies, contracts, migration steps, compatibility risks, and rollback seams.
09
Domain model
Verify entities and relationships
Use $diago-engineering-diagram to inspect this repository's order domain and render a data-model view. Show verified entities, keys, constraints, cardinality, and proposed changes without inventing missing relationships.
10
Migration timeline
Sequence engineering milestones
Use $diago-engineering-diagram to turn this migration plan and repository evidence into an engineering timeline. Show phases, dependencies, owners, validation gates, and rollback milestones; use ordered phases when dates are not confirmed.
11
Control placement
Show responsibility by layer
Use $diago-engineering-diagram to show where authentication, authorization, validation, observability, and data-protection controls are enforced across this system's layers. Mark gaps and unsupported assumptions explicitly.Claude Code Replace $diago-engineering-diagram with /diago:diago-engineering-diagram, or use /diago:diago-review-diagram for review prompts.
Source checkout · 11 diagram models
Inspect coupling, access, and incident causes.
New dependency graphs, security matrices, and fishbones share Diago’s light/dark presentation and preserve explicit evidence and unknowns.
Explore the three new models →
Source checkout additions after v0.7.0.
System map · current source checkout
How Diago works
Trace an engineering question through Diago’s agent guidance, local CLI/MCP tools, evidence checks, renderer routing, and standalone HTML. Each perspective cites the source files behind its claims.
Open the Diago system map → · Authoring guide
The map describes the current source checkout; the v0.7.0 release predates some of these additions.
A few useful answers
What to know before your first diagram.
Quick answers about Diago, its MCP tools, and the artifacts you can keep.
What is Diago?
Diago is an open-source software engineering diagram toolkit for Codex and Claude Code. It combines agent skills, a local Model Context Protocol (MCP) server, and deterministic renderers to turn source evidence into interactive HTML diagrams.
Which diagrams can Diago create?
Diago supports eight views: architecture, sequence, workflow, dataflow, lifecycle, data model, timeline, and layers. Choose a view for the question you need to answer, such as request ordering or entity relationships. Explore all eight views.
Does Diago automatically understand my code?
Your agent inspects the repository and authors the diagram JSON. Diago helps plan the view, validate the input, render the result, and review the plan. Evidence references and assumptions remain explicit; you still review claims against their sources.
Does Diago need a hosted service or API key?
Diago runs locally on Node.js 18 or newer through stdio MCP or its CLI. It needs no separate Diago account, hosted endpoint, or API key. Your chosen agent's account, model access, and data-handling settings still apply. See setup options.
Can I share and update the diagrams?
Yes. Keep the source JSON and generated standalone HTML together. Open the HTML in a browser, share it for review, and regenerate it when the source changes. Check the content for private information before sharing outside your team.
Is Diago free, and which features are released?
Diago is available under the MIT license, with third-party notices preserved. Diago v0.7.0 includes eight diagram views and seven MCP tools, including evidence workflow planning. Update an older plugin installation to use the new tool. Check releases.
Build with shared understanding