diagonaldiagrams
Install Star
Skill Install diagonaldiagrams from https://github.com/lucas19919/diagonaldiagrams

Diagrams your agent gets right.

An AI agent describes a diagram in text. diagonaldiagrams draws it as an SVG and checks it for mistakes.

An animated architecture diagram of an AI agent platform. A chat message is traced in coral from Web chat through the API gateway to the Agent, on to diagonaldiagrams and into the Object store, while dots stream along the dashed background events to Postgres and Traces.
A chat request traced through an agent platform.

How it works.

1. Describe. The agent writes a short description of the diagram, in Mermaid, JSON or CSV.

2. Draw. diagonaldiagrams lays it out and saves an SVG file.

3. Check. It looks for text on top of text, arrows through boxes, and words that don't fit their shape. It prints one line of JSON: all clear, or what's wrong and how to fix it. The agent reads that line instead of a screenshot.

$ diagonaldiagrams mermaid flow.mmd -o flow.svg
{"ok": true, "svg": "flow.svg", ..., "items": 3,
 "layout": ["row 1: Start", "row 2: Ready? (decision)", "row 3: Done"]}

Real output for a three-box flowchart, with the file paths shortened. If something is wrong, ok is false and each problem has a fix.

Install it.

Pick the way that matches how you use your agent. Needs Python 3.11 or newer.

Paste this to your agent. It follows the install skill: it downloads the repo, checks that it works, and copies the drawing skill into its skills folder.

Install diagonaldiagrams from https://github.com/lucas19919/diagonaldiagrams

Adds the tool, and the instructions Claude uses to draw with it.

/plugin marketplace add lucas19919/diagonaldiagrams
/plugin install diagonaldiagrams@diagonaldiagrams

Installs the diagonaldiagrams command from PyPI. Your agent can run it from any terminal.

pip install diagonaldiagrams

Any app that supports MCP can call diagonaldiagrams as a tool. Add this to the app's MCP settings. It needs uv, which runs the package from PyPI. The server is listed in the official MCP registry as io.github.lucas19919/diagonaldiagrams.

{
  "mcpServers": {
    "diagonaldiagrams": {
      "command": "uvx",
      "args": ["diagonaldiagrams", "mcp"]
    }
  }
}

Download the .mcpb file from the latest release and open it with Claude Desktop. No settings to edit, but Python 3.11 or newer must already be installed.

Examples

How an NVIDIA GPU gets made

Design, TSMC, memory on one interposer, a rack builder, then the clouds that buy it.

How an NVIDIA GPU gets made: design, TSMC, CoWoS packaging with memory, then a rack builder and a cloud.

Palantir, from raw data to a decision

Data lands, the Ontology is built, and a model writes an action back.

Palantir, from raw data to an AI decision: data lands, the Ontology is built, and a model writes an action back.

A Falcon 9 mission

Countdown, liftoff, separation. The booster flies home. The second stage goes on to orbit.

A Falcon 9 mission: countdown, liftoff, separation, the booster flying home, the second stage going on to orbit.

Results

At 40 steps, 6.4k tokens. Mermaid CLI climbs to 15.4k with screenshot debugging loops. Pele costs least, but performs no collision check.

diagonaldiagrams 0.8.0 benchmarked against Mermaid CLI and Pele on 2026-10-19 across eight independent agent runs (from 5 to 40 steps).

6.4k tokens At 40 steps

Flat token cost

Cost stays between 4.4k and 6.4k as diagrams grow. Mermaid CLI spirals up to 15.4k attempting screenshot visual fixes.

152 ms 15× faster

Instant layout & audit

152 ms median from bytecode for a 20-step flowchart. Renders SVG and audits text/arrow collisions in one pass.

100% First pass

Zero collisions

All 24 benchmark figures passed collision audit. Judged clearer in 100% of README column layouts and 85%+ on slides.

Click chart to expand
Line chart of tokens per flowchart. diagonaldiagrams stays between 4.4k and 6.4k. Mermaid CLI climbs from 1.8k to 15.4k. Pele stays under 2.7k until 6.3k at 40 steps.
Tokens spent per flowchart size. diagonaldiagrams stays nearly flat (4.4k to 6.4k) as complexity grows. Mermaid CLI climbs sharply as agents burn tokens taking screenshots to correct overlapping text.
Bar chart of one 20-step flowchart, a new process each time: diagonaldiagrams 152 ms, Pele 101 ms, Mermaid CLI 2,340 ms, about 15 times as long.
Render latency for a 20-step flowchart (median of 7 fresh runs from bytecode). diagonaldiagrams runs in 152 ms including collision auditing; Mermaid CLI takes 2,340 ms through headless Chromium.
Bar chart of the share of blind judgments calling diagonaldiagrams clearer, with a line at 50 percent. Against Pele: 85 percent on a slide, 100 for column flows, 75 for our architecture. Against Mermaid CLI: 97, 100, 88 and 50.
Share of double-blind human judgments picking diagonaldiagrams as clearer. Won 100% of README column flowcharts and 85%+ of slide presentations against both Pele and Mermaid CLI.
Framework Tokens (8 flows) Tool calls Screenshots Total time Layout audit
diagonaldiagrams 0.8 43.8k flat across scale 69 calls 9 shots 7 min 24 / 24 verified
Pele 23.9k reads no skill 57 calls 18 shots 5 min No collision check
Mermaid CLI 47.8k climbs with size 79 calls 32 shots 13 min Manual screenshot loops
How we tested (methodology & reproducible scripts)
  • Speed: A fresh process per figure. diagonaldiagrams was measured from bytecode (median of 7 runs). Pele and Mermaid CLI were measured under identical system conditions.
  • Tokens: Counts agent prompt output, tool inputs/returns, files read, and screenshots. Harness instructions and thinking tokens are excluded. Two fresh agent runs per test point.
  • Quality: Double-blind evaluation by independent reviewers presented in both orders. The column numbers reflect re-evaluation with --fit column.
  • Reproducibility: All benchmark scripts, test prompt templates, and raw metric tables are committed in the repository under bench/.
Open file