Skip to main content
O tool @diagram renderiza diagramas de arquitetura, dependências, fluxo e ER em PNG, SVG ou JPG a partir de Graphviz DOT — com os textos nítidos e exatamente corretos, porque os rótulos vêm do layout engine, não de pixels “chutados” por um modelo de visão. O Graphviz é embedado: o go-graphviz traz o engine upstream compilado para WebAssembly, executado pelo runtime wazero (Go puro). Portanto funciona sem cgo, sem instalação e sem rede — o mesmo DNA self-contained do TTS/STT embedados e das notas de voz puro-Go. Quando há um Graphviz do sistema (dot) no PATH, o backend passa a usá-lo por padrão (backend=auto): renderizar o mesmo DOT via fontconfig + as fontes do SO + cairo gera saída mais nítida e melhor diagramada. O engine embedado continua sendo o fallback, então o tool nunca exige instalação. Veja Backend de renderização.
Para qualquer diagrama de nós/arestas, prefira @diagram ao @image. O @image gera uma imagem raster e erra letras; o @diagram é determinístico e os nomes saem 100% corretos. SVG é infinitamente escalável; PNG com dpi=300 é qualidade de impressão.

​
Uso

O LLM invoca @diagram automaticamente quando você pede um diagrama de arquitetura/dependências como imagem — ele escreve o DOT (os modelos são bons em DOT) e renderiza aqui. São dois subcomandos: render (DOT → imagem) e gomod (grafo de imports real de um módulo Go → imagem).

​
Subcomando render

Renderiza DOT — inline (dot) ou de um arquivo .dot (file) — para uma imagem.

​
Argumentos

​
Subcomando gomod

Constrói o grafo de imports real de um módulo Go (via go list -json ./...) e o renderiza, clusterizado por diretório de topo — um grafo de dependências fiel ao código 1:1, sem enumerar pacote na mão.

​
Argumentos

Use dotOnly: true para obter o DOT gerado e editá-lo (cores, agrupamentos, rótulos) antes de renderizar com render. Para diagramas focados, aponte root para um subdiretório (ex.: ./cli) — o grafo do módulo inteiro pode ficar muito largo.

​
Saída

Para render e gomod (sem dotOnly), o tool grava o arquivo e retorna um resumo com caminho, formato, tamanho e — para raster — as dimensões:
Com dotOnly: true, o gomod retorna o próprio código DOT (texto), pronto para editar ou versionar.

​
Backend de renderização

O @diagram renderiza o mesmo DOT por um de dois engines. O DOT gerado é idêntico — só muda quem rasteriza: O embedado rasteriza com gg/freetype (sem cairo/pango), então o PNG/JPG sai um pouco mais suave que o do dot nativo. Para minimizar isso, o embedado usa fontes Go embarcadas com hinting completo e escolhe a família certa por nome (proporcional vs monospace, regular vs negrito) — texto nítido e consistente em qualquer máquina. O dot do sistema usa fontconfig + as fontes do SO + cairo, então fica ainda um pouco mais polido. No modo auto, se o render pelo dot do sistema falhar, há fallback transparente para o embedado.
Quer paridade total sem instalar nada? Use format=svg. O SVG é vetorial e idêntico ao do dot nativo (mesmo engine de layout) — por isso, quando o engine embedado renderiza e você não passa format, a saída usa SVG por padrão. Um format explícito ou uma extensão de arquivo reconhecida (.png/.svg/.jpg) sempre prevalecem.

​
Configuração

Três formas, da mais ampla à mais específica:
  • Variável de ambiente CHATCLI_DIAGRAM_BACKEND=auto|system|embedded (process-wide)
  • Argumento backend por chamada (sobrepõe o env): {"dot":"...","backend":"system"}
  • /config diagram mostra o backend configurado, o efetivo (após resolver o auto) e se há um dot instalado, com a versão:

​
Notas

  • Não é read-only e não é concurrency-safe: o tool grava um arquivo (e o gomod invoca go list), então passa pela confirmação de segurança padrão e não entra em lotes paralelos read-only.
  • Embedado de verdade: o Graphviz roda como WebAssembly via wazero — nada para instalar, funciona offline já no primeiro uso, em qualquer SO/arquitetura. Com um dot do sistema instalado, o backend auto o usa automaticamente para saída mais nítida (veja Backend de renderização).
  • Engines suportados: dot (hierárquico, default), neato/fdp/sfdp (força), circo (circular), twopi (radial), osage/patchwork (clusters/treemap).
Combine com o @docs-flatten e o @context: monte uma base de conhecimento do projeto e peça um diagrama de arquitetura — a IA usa o que aprendeu para escrever o DOT e o @diagram para renderizá-lo com fidelidade.