If you use a coding agent like Claude Code, Codex or Pi, you have probably asked it for an architecture diagram. And you probably got something a little off: two boxes on top of each other, a label spilling out of its box, an arrow cutting straight through a node.
Why it happens
To draw an SVG, the agent has to work out where every box, arrow and label goes. Language models are good at describing a system. They are not good at geometry.
I measured it. In a bench with Codex (8 tasks, 3 runs each), 20 of 24 hand-written SVG diagrams had layout defects. They were also the most expensive in tokens, because the agent writes the whole drawing as output, the priciest kind of token.
The idea: split the what from the where
So I built trazo around one rule: the agent says what is in the system, and trazo decides where it goes.
The agent writes semantic JSON, with no coordinates and no styles:
{
"type": "architecture",
"title": "Orders",
"nodes": [{ "id": "web", "kind": "client" }, { "id": "api" }, { "id": "db", "kind": "database" }],
"edges": ["web -> api: HTTPS", "api -> db: SQL"]
}
And trazo turns it into an interactive HTML page:
trazo make demo.json
The HTML is one self-contained file: no server, no network. You can pan, zoom, hover a node to see its connections, and export to SVG or PNG.
The numbers
Same bench, three ways to get the diagram:
| Approach | Diagrams with layout defects |
|---|---|
| Hand-written SVG by the agent | 20 of 24 |
| Mermaid | 7 of 24 |
| trazo | 0 of 46 |
To be fair: Mermaid used about 35-40% fewer tokens than trazo, and GitHub renders it right inside Markdown. If that is what matters most to you, Mermaid is a good choice. trazo wins on layout, on input validation, and on determinism: the same JSON always gives the same HTML, byte for byte.
Method and raw numbers: bench/README.md
What else it does
-
Four diagram types: architecture, workflow (with lanes), ERD (foreign keys point at columns, not only tables) and sequence (with
alt,optandloopfragments). - Errors an agent can act on: each one names the exact path in the JSON and carries a hint, so the agent fixes its own input. In the recorded runs, Claude Sonnet 5.5 got a valid diagram on the first try every time.
- A skill for agents: it tells the agent to read the code before drawing, draw only what it found, and cite where each part lives.
What it does not do: only four types (Mermaid, PlantUML and D2 cover many more), and no inline rendering in Markdown.
Try it in three steps
- Install it (Node.js 22 or later):
npm i -g @heidenber/trazo
- Optional: install the skill by following these steps, or ask your agent to do it.
- Ask your agent for a diagram:
> Use trazo to draw the architecture of this project. Run
trazo example architectureto see the format, write the JSON, runtrazo makeand tell me where the HTML file is.
Feedback
trazo is open source under Apache-2.0: https://github.com/heidenber/trazo
The first outside contribution is already merged, and there are a few good first issues open if you want to help. I'd love to hear which diagram type you are missing and how it goes with your agent.

Top comments (0)