Skip to main content
The @diagram tool renders architecture, dependency, flow and ER diagrams to PNG, SVG or JPG from Graphviz DOT — with crisp, exactly-correct text, because the labels come from the layout engine, not from pixels a vision model guesses. Graphviz is embedded: go-graphviz ships the upstream engine compiled to WebAssembly, run on the pure-Go wazero runtime. So it works with no cgo, no install and no network call — the same self-contained DNA as the embedded TTS/STT and the pure-Go voice notes. When a system Graphviz (dot) is on PATH, the backend uses it by default (backend=auto): rendering the same DOT through fontconfig + the OS fonts + cairo yields crisper, better-laid-out output. The embedded engine stays the fallback, so the tool never requires an install. See Rendering backend.
For any node/edge diagram, prefer @diagram over @image. @image produces a raster image and mangles letters; @diagram is deterministic and the names come out 100% correct. SVG is infinitely scalable; PNG with dpi=300 is print-grade.

​
Usage

The LLM invokes @diagram automatically when you ask for an architecture/dependency diagram as an image — it writes the DOT (models are good at DOT) and renders it here. There are two subcommands: render (DOT → image) and gomod (real import graph of a Go module → image).

​
render subcommand

Renders DOT — inline (dot) or from a .dot file (file) — to an image.

​
Arguments

​
gomod subcommand

Builds the real import graph of a Go module (via go list -json ./...) and renders it, clustered by top-level directory — a 1:1, code-faithful dependency graph with no manual package enumeration.

​
Arguments

Use dotOnly: true to get the generated DOT and edit it (colors, grouping, labels) before rendering with render. For focused diagrams, point root at a subdirectory (e.g. ./cli) — the whole-module graph can get very wide.

​
Output

For render and gomod (without dotOnly), the tool writes the file and returns a summary with path, format, size and — for raster — the dimensions:
With dotOnly: true, gomod returns the DOT source itself (text), ready to edit or version.

​
Rendering backend

@diagram renders the same DOT through one of two engines. The generated DOT is identical — only who rasterizes it changes: The embedded engine rasterizes with gg/freetype (no cairo/pango), so its PNG/JPG comes out slightly softer than a native dot render. To minimize that, the embedded path uses bundled Go fonts with full hinting and picks the right family by name (proportional vs monospace, regular vs bold) — crisp, consistent text on every machine. A system dot uses fontconfig + the OS fonts + cairo, so it stays a touch more polished. Under auto, if a system dot render fails there is a transparent fallback to the embedded engine.
Want full parity with no install? Use format=svg. SVG is vector and identical to a native dot render (same layout engine) — so when the embedded engine renders and you don’t pass format, the output defaults to SVG. An explicit format or a recognized file extension (.png/.svg/.jpg) always wins.

​
Configuration

Three ways, from broadest to most specific:
  • Environment variable CHATCLI_DIAGRAM_BACKEND=auto|system|embedded (process-wide)
  • Argument backend per call (overrides the env): {"dot":"...","backend":"system"}
  • /config diagram shows the configured backend, the effective one (after resolving auto) and whether a dot is installed, with its version:

​
Notes

  • Not read-only and not concurrency-safe: the tool writes a file (and gomod shells out to go list), so it goes through the standard security confirmation and never joins a parallel read-only batch.
  • Truly embedded: Graphviz runs as WebAssembly via wazero — nothing to install, works offline on first use, on any OS/architecture. With a system dot installed, the auto backend uses it automatically for crisper output (see Rendering backend).
  • Supported engines: dot (hierarchical, default), neato/fdp/sfdp (force-directed), circo (circular), twopi (radial), osage/patchwork (clusters/treemap).
Combine with @docs-flatten and @context: build a knowledge base of the project and ask for an architecture diagram — the AI uses what it learned to write the DOT and @diagram to render it faithfully.