Diago

Diago renders diagrams from typed JSON specs. Describe what's connected to what; diago lays it out and draws it as SVG, PNG, Unicode text art, draw.io XML or Excalidraw JSON (the last two in beta), and it renders Mermaid files as they are. It is built for AI agents as much as for people: agents write valid JSON far more reliably than a diagram DSL, every spec has a JSON Schema, and the same spec always renders to the same bytes.

Every diagram and every diff also draws as Unicode text art, to read in a terminal, a code block or a pull request:

Documentation at diago.dev: getting started, guides, agents, reference and the gallery.

Install

On macOS or Linux:

curl -fsSL https://diago.dev/install.sh | sh

On Windows, in PowerShell:

irm https://diago.dev/install.ps1 | iex

The script downloads the latest release for your system, checks it against the release's checksums.txt and puts diago in ~/.local/bin (on Windows it also adds that folder to your Path); DIAGO_INSTALL_DIR changes the folder. Getting started has the details and a manual download. Or, with Go 1.26+:

go install github.com/oxforge/diago/cmd/diago@latest

diago is at 0.x: a release may reject a spec the previous one accepted, change an exit code or change what a render draws, and its release notes list those breaking changes first. To stay on one version, give the script that version (curl -fsSL https://diago.dev/install.sh | DIAGO_VERSION=vX.Y.Z sh), or go install …@vX.Y.Z.

PNG output also needs resvg 0.26 or newer (brew install resvg or cargo install resvg); every other format is pure Go.

Usage

cat > hello.json <<'EOF'
{
  "type": "flow",
  "nodes": [
    {"id": "a", "label": "Hello", "shape": "rounded"},
    {"id": "b", "label": "World"}
  ],
  "edges": [{"id": "a-b", "from": "a", "to": "b"}]
}
EOF

diago render hello.json > hello.svg             # or -format png, text, drawio, excalidraw
diago render -format text hello.json            # Unicode text art, in the terminal
diago check -strict hello.json                  # advisories, without rendering
diago diff hello.json hello-v2.json > diff.svg  # what changed between two versions
diago import diagram.mmd > spec.json            # from Mermaid

diago help <verb> prints a verb's flags; the CLI reference covers them all.

For agents

This repository is also a Claude Code plugin. Its two skills teach an agent to draw with diago and to show a diagram wherever it presents structure, and its hook adds that rule to every session. With diago on PATH:

claude plugin marketplace add oxforge/diago
claude plugin install diago@diago

The plugin follows diago's releases; see updating it. Any other agent with a shell: diago.dev/docs/agents/other-agents.

Development

Needs just (brew install just; bare just lists every recipe) and optionally golangci-lint.

just build          # bin/diago
just install        # go install ./cmd/diago
just test           # all Go tests
just lint           # golangci-lint
just schemas        # regenerate schemas/{flow,sequence,class}.json; required after any change under internal/schema/

AGENTS.md describes the code layout and the conventions, for people and coding agents alike. To investigate a layout or routing bug, start from debug logging.

License

MIT, see LICENSE.