diagonaldiagrams

diagonaldiagrams

diagonaldiagrams is a Python library and MCP server that lets an AI agent draw diagrams and charts as SVG, and check them for overlapping text, arrows through boxes and text that spills, before showing them.

[Site](https://lucas19919.github.io/diagonaldiagrams/): filmed examples, benchmarks and a gallery.

How it works

1. Describe. The agent writes a short description of the figure, in Mermaid, JSON or CSV.
2. Draw. diagonaldiagrams lays it out and saves an SVG.
3. Check. It audits the drawing and prints one line of JSON: all clear, or what is 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"]}

When ok is false, each error comes with a fix.

Install

Needs Python 3.11 or newer.

Command line

pip install diagonaldiagrams

MCP (Cursor, Claude Desktop and other MCP apps). Add this to the app's MCP settings; it needs uv. The server is in the official MCP registry as io.github.lucas19919/diagonaldiagrams.

{

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

Claude Desktop can also open the .mcpb file from the latest release.

Claude Code

/plugin marketplace add lucas19919/diagonaldiagrams

/plugin install diagonaldiagrams@diagonaldiagrams

Any other agent: tell it Install diagonaldiagrams from https://github.com/lucas19919/diagonaldiagrams. It follows the install skill, then draws with the drawing skill. The short version for models is llms.txt.

What it draws

• describe prints the spec shape for any figure type.
• --fit column sizes a figure for a README or docs page. slide is the default, and page is for print.
• story turns one figure into several views in one page, and --gif films it when ffmpeg is installed.
• apply edits a spec with a JSON patch, and export writes PNG, PDF, draw.io or Excalidraw files.

How it compares

Measured on 2026-10-19 against Mermaid CLI and Pele, on version 0.8.0, with the same four flowcharts of 5 to 40 steps.

• Speed. A 20-step flowchart takes 152 ms, about 15 times faster than Mermaid CLI (2,340 ms) and about 1.5 times slower than Pele (101 ms).
• Tokens. An agent used 4.4k to 6.4k tokens per figure at every size. At 5 to 20 steps Pele and Mermaid CLI used fewer (1.3k to 4.0k). At 40 steps diagonaldiagrams used 6.4k, Pele 6.3k and Mermaid CLI 15.4k. This is two runs, so treat it as a small sample.
• Quality. In blind pairs, diagonaldiagrams was judged clearer than Pele 85% of the time and than Mermaid CLI 97% of the time on slide-sized figures. It lost where an architecture translated from Mermaid was sized for a narrow column: 0 of 8 against Pele.

The full tables, the method and the scripts to rerun them are in bench/.

Develop

python -m unittest discover tests/unit   # unit tests

python tests_smoke.py # the command-line contract python scripts/golden.py # the reference figures, byte for byte

How the engine is put together: docs/ARCHITECTURE.md. How releases are made: PUBLISHING.md.

License

MIT. See LICENSE.