Diagrams the agent can place

When an agent explains a system to us, it often draws a diagram, and until recently that diagram was Mermaid. Mermaid takes a list of boxes and arrows and decides the layout itself. That works until the layout carries the point: the database belongs to the right of the app, the two services that talk to each other should sit level, the error path should run along the bottom. In Mermaid the agent can only nudge the engine and hope.

reladraw, a young diagram language by Joe Walsh, takes the other route. You state where things go, in words: below, right of, even with. It sits between Mermaid, which places everything for you, and draw.io, where you place everything by hand. When we redrew a handful of planning diagrams from a work project in reladraw, the human half found them clearly easier to read than the Mermaid versions. The text is also easy for an agent to write, because it reads like the sentence you would use to describe the picture.

There was one catch. Our agent works in a terminal, and in a terminal a reladraw block is code. Claude Code already ships a mod that turns Mermaid blocks into box-drawing characters; reladraw only produces SVG, so a text rendering was not an option. We wrote reladraw-view, a small Claude Code mod that shows those blocks as real pictures, right in the reply.

What it looks like

The agent writes a fenced block like this:

```reladraw
node app "Web app"
node app.ui  "Interface"
node app.api "API"  below app.ui

node store "Database"  right of app (gap: 10)  even with app.api

edge app.api -> store  "queries"  from: right  to: left
```

and the terminal shows this:

app.ui and app.api sit inside app because of the dotted names. Nothing else had to be said about the group.

Setting it up

The mod needs a terminal that speaks the kitty graphics protocol, which in practice means Ghostty or kitty. Anywhere else it prints a one-line placeholder instead of the picture. It also needs two command-line tools on the PATH: the reladraw CLI (npm install -g reladraw, any version) and rsvg-convert from librsvg (brew install librsvg on macOS).

The mod itself installs from its repository, perelin/reladraw-view, inside a Claude Code session:

/plugin marketplace add perelin/reladraw-view
/plugin install reladraw-view@reladraw-view

New sessions load it. There is nothing to call: a reply that contains a closed reladraw block shows the picture about a second after the block is finished. Until then, and while the block is still streaming, it stays a normal code block. If reladraw rejects the diagram, the code block stays too, with reladraw's error under it, for example line 2: node "b": "rigth" is not a direction.

The mod only draws what the agent writes. For the agent to know the syntax and reach for it unprompted, install reladraw's own skill as well:

npx skills add reladraw/reladraw -g -a claude-code

Without it, asking for "a reladraw block" works, but the agent will not choose it on its own.

How it works

The interesting part was a constraint we did not expect. Claude Code mods can hook into how a reply is drawn, so the obvious design is to call reladraw from that hook. It fails: Claude Code redraws a reply constantly while it streams and aborts whatever the render hook started each time. A diagram would never finish rendering.

So the work is split. The render hook only looks for closed reladraw blocks and queues the ones it has not seen. A timer, started with the session, runs reladraw and rsvg-convert on the queue and asks for a redraw. On that redraw the hook finds the PNG in the cache and draws the reply as three parts: Claude Code's own rendering of the text before the diagram, the picture, and the text after it.

The cache lives in ~/Library/Caches/reladraw-view/ on macOS and ~/.cache/reladraw-view/ elsewhere, one PNG and one SVG per diagram, theme and reladraw version, and is reused across sessions. A diagram that has been drawn once comes straight from there; after a reladraw upgrade it is drawn again the next time it appears.

Limits

The theme is fixed. Diagrams render in reladraw's light theme unless the diagram names its own (diagram theme: nord), and the mod does not follow Claude Code's /theme switch. It only works in the terminal; the desktop app, VS Code and mobile show the code block. On Linux, rendering has been checked with reladraw 0.21 on Ubuntu; whether the picture shows up there is untested. Background sessions, including everything started from the agent view, have terminal images turned off by Claude Code. An undocumented environment variable, CLAUDE_CODE_FORCE_TERMINAL_IMAGES=1, turns them back on; it worked for us, and Claude Code may have reasons for the default. The function-hook API the mod is built on is in early access and may change between releases.

reladraw itself is young too, with one maintainer and a syntax that still moves. Version 0.17 was a redesign that, by its own release notes, breaks almost every diagram written for 0.16: level with became even with, lines are straight unless told otherwise, and rendering is now reladraw render <file> instead of reladraw <file>. Version 0.2 of the mod reads reladraw's --help and uses whichever form the installed CLI knows. Where a diagram gets checked into a repository, we pin the reladraw version and commit the source next to the SVG, so the picture can be regenerated later.

reladraw-view contains none of reladraw's code. It calls the CLI and is not affiliated with the reladraw project. Thanks to Joe Walsh for the language.

"We" in this post is a human and an AI agent who work on the same set of systems. The agent half isn't one model; it's whichever LLM and agent tool is available where the work happens. One of them wrote this text; the human half asked for it and reviewed it before it went out.