Skip to content

Diagram ​

Give diagram a text description of a picture and it renders that text to a diffable SVG, then makes you look at the result before it ships. The one idea is that agents write raw SVG badly because they cannot spatially reason about coordinates blind, but Claude can see images, so the loop closes itself: write source you can diff, render it, look at the raster, fix, repeat. That loop is the whole product, and it is the same loop whether the source is a Graphviz graph, a Vega-Lite chart, or hand-authored SVG. One module, not three.

A shared spine does the rendering and the verifying, and sub-skills sit on top, one per authoring concern. Every renderer is a single static binary bundled under harness/bin/ the way nushell is, so the module runs on a box that fights npm installs, and an installed copy finds them through a stamped HARNESS_BIN.

In Practice ​

nu scripts/render.nu render graph.dot                  source to svg, renderer inferred from the extension
nu scripts/render.nu render chart.vl.json --format png svg then a png through resvg
nu scripts/render.nu render flow.d2 --format pdf       svg then a pdf through vl-convert, no chromium
nu scripts/check.nu check graph.svg                    rasterise an svg so you can look at it
nu scripts/optimise.nu optimise out.svg                svgo shrink before it ships
nu scripts/optimise.nu embed-font out.svg              inline the font so a dot svg is portable

The module is skill-triggered, not a command: ask for a diagram, a chart, a dependency graph, or an icon and the right sub-skill picks it up. The scripts are the shared machinery every route runs through.

The Spine ​

Three nushell wrappers, renderer-agnostic, so a sub-skill dispatches through one place instead of shelling a binary itself.

  • render.nu turns a source into an SVG, the common diffable artifact, then optionally on to a PNG or PDF. It infers the renderer from the extension, resolves the binary, injects the default font, and lifts every label off the renderer's low baseline.
  • check.nu rasterises an existing SVG to a PNG so the agent can read it back. This is tier 2 of the verify loop.
  • optimise.nu is the publish step: svgo to shrink the artifact, and an embed-font pass that inlines the font as a data-URI @font-face so a named-font SVG renders standalone.

The Routes ​

Each sub-skill carries its own trigger and shares the one spine.

  • svg, hand-authored, generated, or edited vector graphics for a bespoke icon, logo, glyph, or pattern. Three lanes: write it directly for small art, run a generator script for repeated or data-driven shapes, or take an existing SVG in and recolour, simplify, or optimise it.
  • diagrams, node-and-edge pictures a layout engine places for you. Graphviz dot owns dense dependency, call, and state graphs; d2 owns architecture and general flow with nicer default styling. You describe the graph in a DSL you can diff and let the engine position the nodes, then rasterise and look.
  • charts, data charts from a declarative Vega-Lite JSON spec, rendered by vl-convert. The spec is validated as it compiles, so a bad field, mark, or channel is caught before any output is written.

The Verify Loop ​

Nothing ships that the agent has not looked at. The loop has two tiers, and the cheap one always runs.

  • Tier 1, the compile loop. A malformed source fails to render and the renderer's own error comes straight back on stderr with a line number. The agent fixes the source and re-renders. Graphviz, d2, and Vega-Lite all give precise messages, so this converges on its own, and for charts the Vega-Lite compile is itself the validate-before-render gate: a bad spec writes no file.
  • Tier 2, the look. Once it compiles, check.nu rasterises the SVG to a PNG and the agent reads it back, checking for overlapping nodes, clipped labels, bad spacing, or an unreadable scale. Layout only shows in the picture, so this tier is mandatory when layout matters, capped at three or four passes so it does not spiral.

Formats and Fonts ​

One source emits three formats. The SVG is always produced first as the common artifact, then a PNG derives from it through resvg and a PDF through vl-convert's svg2pdf, which needs no headless browser. So a d2 flow, a dot graph, or a Vega-Lite chart all reach SVG, PNG, and PDF the same way.

The module default font is monogram, a pixel face bundled with the module and applied to the diagram and SVG routes. Charts keep Vega-Lite's own clean sans, because a pixel face reads badly on a data chart. Neither renderer centres a label on its ink, so the spine lifts every label a few units at render time, tunable with --label-dy.

Renderers and Portability ​

The live renderer set is d2, Graphviz dot, resvg for rasterising, and vl-convert for charts and the SVG-to-PDF path, plus svgo for the publish shrink. On Windows they are committed executables under harness/bin/. On mac and Linux, share/fetch-renderers.sh pulls the same pinned versions per platform, and the resolvers only consider a .exe on Windows so the fetched extensionless binaries win everywhere else.

An installed project finds all of this because the install stamps env.HARNESS_BIN, pointing at the harness bin/ directory, into the project's settings, the bin twin of the HARNESS_NU interpreter stamp. doctor reports the stamp and doctor --fix re-lays it.

Connects to ​

  • Lecture (formerly chalk), which explains code as a slide deck with drawn D2 diagrams; diagram is the file-producing counterpart when you want a diffable SVG rather than an inline lecture picture.
  • Atlas, which renders its d2 diagram specs to inline SVG through this toolkit as a wants dependency.
  • Installer, which ships the module as the diagram part and stamps HARNESS_BIN so the bundled renderers resolve from an installed copy.