diago System map →

From a question to a diagram

Create architecture diagrams with Codex or Claude Code.

Diago is an open-source Model Context Protocol (MCP) toolkit that helps your agent turn repository evidence into interactive software engineering diagrams. Install the plugin, ask a focused question, and keep the JSON and standalone HTML for review.

By Amir Taherkhani · Updated

1. Install Diago in your agent

You need Node.js 18 or newer and access to Codex or Claude Code. The plugin bundles its skills and local stdio MCP server. Diago does not need a separate account, hosted endpoint, or API key; your agent's account and model requirements still apply.

Codex plugin

codex plugin marketplace add amirtaherkhani/diago
codex plugin add diago@diago

Claude Code plugin

Run these commands inside Claude Code:

/plugin marketplace add amirtaherkhani/diago
/plugin install diago@diago
/reload-plugins

After installing, open a new agent thread in the repository you want to understand. For a direct MCP connection, use the stdio server setup instructions.

2. Ask an engineering question

A useful prompt names the scope, the reader, and the decision. In Codex, try:

Use $diago-engineering-diagram to trace checkout from its API entry point
through payment and persistence. Inspect the repository for evidence.
For a backend reviewer, show an architecture view for ownership and a
sequence view for request ordering. Label assumptions and failure paths.

In Claude Code, invoke the skill with:

/diago:diago-engineering-diagram
Trace checkout from API entry to payment and persistence. Inspect the code,
show ownership and request ordering, and label assumptions and failure paths.

Replace “checkout” with a feature that exists in your repository. Your agent reads the available evidence and authors the diagram JSON. Diago's tools help select the view, review the plan, validate the JSON, and render HTML.

3. Choose the diagram that answers your question

Use one focused view per question. For checkout, architecture explains ownership; sequence explains the order of calls. Split a crowded diagram into smaller views.

Your questionDiagram view
Which components own the work?Architecture
In what order do calls and responses happen?Sequence
Which decisions and approvals control the work?Workflow
Where does data move and change?Dataflow
Which states, guards, and transitions exist?Lifecycle
Which entities and relationships define the domain?Data model
Which milestones depend on earlier work?Timeline
Where are responsibilities and controls enforced?Layers

Open the live workbench and select a view to see an interactive example.

4. Render a ready-made architecture example

You can try the renderer without an agent. Clone the source and render the bundled plugin-request example:

git clone https://github.com/amirtaherkhani/diago.git
cd diago
node bin/diago.mjs doctor
node bin/diago.mjs render architecture examples/plugin-request.architecture.json diagram.html --quality showcase

Open diagram.html in your browser. The input shows an engineering task moving through the agent, diagram plan, renderer, and review loop. Read the example JSON alongside the output to see how the source defines the diagram.

5. Review before sharing

  • Follow each important claim back to code, a contract, or another named source.
  • Keep verified behavior, assumptions, and proposed changes distinct.
  • Check failure paths, ownership, and anything collapsed or omitted from the view.
  • Keep the JSON with the HTML so you can update and regenerate the diagram.
  • Review private code and customer details before sharing artifacts outside your team.

For a second pass in Codex:

Use $diago-review-diagram to review this diagram against the repository.
List unsupported claims, missing boundaries, ambiguous edges, and visual issues.

In Claude Code, use /diago:diago-review-diagram with the same review request.

Keep exploring