> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagrams (@diagram)

> Render architecture, dependency, flow and ER diagrams to PNG/SVG/JPG from Graphviz DOT — with crisp, 100% correct text labels. Graphviz runs embedded (WebAssembly), no install; if a system Graphviz ('dot') is on PATH it is used automatically for crisper fonts and layout.

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](#rendering-backend).

<Tip>
  For **any node/edge diagram**, prefer `@diagram` over [`@image`](/features/image-generation). `@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.
</Tip>

***

## Usage

```text theme={"system"}
<tool_call name="@diagram" args='{"cmd":"render","dot":"digraph{rankdir=LR; cli->agent; cli->llm}","output":"/tmp/arch.png"}' />
<tool_call name="@diagram" args='{"file":"./arch.dot","format":"svg","output":"/tmp/arch.svg"}' />
<tool_call name="@diagram" args='{"cmd":"gomod","root":".","format":"svg","output":"/tmp/imports.svg"}' />
```

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

| Argument  | Description                                                                                                                                                                               | Default                                    |
| :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------- |
| `dot`     | Inline Graphviz DOT source. Exactly one of `dot` \| `file`.                                                                                                                               | *(one of)*                                 |
| `file`    | Path to a `.dot` file to render. Exactly one of `dot` \| `file`.                                                                                                                          | *(one of)*                                 |
| `format`  | `png` \| `svg` \| `jpg`                                                                                                                                                                   | `png` (SVG when embedded with no `format`) |
| `engine`  | Layout: `dot` \| `neato` \| `fdp` \| `sfdp` \| `circo` \| `twopi` \| `osage` \| `patchwork`                                                                                               | `dot`                                      |
| `dpi`     | Raster resolution for png/jpg (30–600, clamped)                                                                                                                                           | `150`                                      |
| `backend` | Rendering engine: `auto` \| `system` \| `embedded`. `auto` prefers a system `dot` if installed (crisper) and falls back to the embedded WASM engine. Overrides `CHATCLI_DIAGRAM_BACKEND`. | `auto`                                     |
| `output`  | Output file path. When omitted, a temp file is written and its path returned.                                                                                                             | *(temp)*                                   |

***

## `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

| Argument                                           | Description                                                        | Default |
| :------------------------------------------------- | :----------------------------------------------------------------- | :------ |
| `root`                                             | Module directory to analyze                                        | `.`     |
| `internalOnly`                                     | Only edges between packages of this module (drop third-party deps) | `true`  |
| `cluster`                                          | Group packages into clusters by top-level directory                | `true`  |
| `style`                                            | `dark` \| `light` \| `plain`                                       | `dark`  |
| `dotOnly`                                          | Return the **generated DOT source** instead of rendering an image  | `false` |
| `format` / `engine` / `dpi` / `backend` / `output` | Same as `render`                                                   | —       |

<Tip>
  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.
</Tip>

***

## 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:

```text theme={"system"}
Diagram rendered → /tmp/arch.png (PNG, 245.1KB)
dimensions: 1200x800
```

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:

| Backend            | Engine                                            | When to use                                                     |
| :----------------- | :------------------------------------------------ | :-------------------------------------------------------------- |
| `auto` *(default)* | system `dot` if on PATH, else the embedded engine | Best default: nicer when available, never breaks                |
| `system`           | native Graphviz (e.g. `brew install graphviz`)    | Force the crisper output (fontconfig + cairo); errors if absent |
| `embedded`         | go-graphviz (WebAssembly/wazero)                  | Force the self-contained engine, no install dependency          |

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.

<Tip>
  **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.
</Tip>

### 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:

```text theme={"system"}
/config diagram
```

***

## 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](#rendering-backend)).
* Supported engines: `dot` (hierarchical, default), `neato`/`fdp`/`sfdp` (force-directed), `circo` (circular), `twopi` (radial), `osage`/`patchwork` (clusters/treemap).

<Tip>
  Combine with [`@docs-flatten`](/features/knowledge-base) 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.
</Tip>