DEV Community

Cover image for I stopped letting my coding agent draw diagrams
Heidenber Palacio Garzón
Heidenber Palacio Garzón

Posted on

I stopped letting my coding agent draw diagrams

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"]
}
Enter fullscreen mode Exit fullscreen mode

And trazo turns it into an interactive HTML page:

trazo make demo.json
Enter fullscreen mode Exit fullscreen mode

Diagram generated by trazo

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, opt and loop fragments).
  • 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

  1. Install it (Node.js 22 or later):
   npm i -g @heidenber/trazo
Enter fullscreen mode Exit fullscreen mode
  1. Optional: install the skill by following these steps, or ask your agent to do it.
  2. Ask your agent for a diagram: > Use trazo to draw the architecture of this project. Run trazo example architecture to see the format, write the JSON, run trazo make and 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)