# Diagrammo

> A diagram-as-code tool. Write plain text `.dgmo` files; get rendered diagrams in a browser editor, a Mac app, your AI tool, or scripts. 50 chart types, 7 palettes. Free. Core library and CLI are MIT-licensed open source.

Diagrammo is built around the DGMO language — a plain-text syntax. Every diagram starts with a first line that declares the chart type (and optional title), followed by data and options. The same `.dgmo` file works across every surface.

## Quick start

- [Browser editor](https://online.diagrammo.app): no install, no sign-up — open it and start typing
- [AI integrations](https://diagrammo.app/ai): one command installs dgmo into Claude Code, Codex, Cursor, or Claude Desktop
- [CLI + npm library](https://diagrammo.app/dev): `brew install diagrammo/dgmo/dgmo` or `npm install @diagrammo/dgmo`
- [Desktop app (macOS)](https://diagrammo.app/app): native app with split-pane editor + live preview

One-command AI installers (requires `brew install diagrammo/dgmo/dgmo` first):
- `dgmo --install-claude-code-integration` — Claude Code + `/dgmo` skill + MCP
- `dgmo --install-codex-integration` — Codex CLI + `AGENTS.md` + MCP
- `dgmo --install-claude-desktop-integration` — Claude Desktop + MCP

## Reference

- Per-chart-type syntax (`https://diagrammo.app/llms/<id>.txt`): plain-text grammar for one type — fetch this, not the full spec, when you know which chart you want. Linked per type below
- [Canonical grammar](https://diagrammo.app/reference): single-URL DGMO spec designed for LLM fetch
- [Full language specification](https://diagrammo.app/llms-full.txt): longer-form grammar in plain text
- [Chart-type guides](https://diagrammo.app/docs): one page per chart type with examples and tips
- [DGMO vs Mermaid / D2 / PlantUML](https://diagrammo.app/compare)

## Choosing a chart type

Match the question to a type, then fetch that type's file from the list below.

- Comparing quantities across categories → bar · over time → line · share of one whole → pie
- Messages between parties in order (API calls, protocols, conversations) → sequence
- A decision or process with branches → flowchart · boxes and arrows with no stricter semantics → boxes-and-lines
- Server/cloud topology with traffic → infra · architecture at context/container/component level → c4
- Statuses something moves through → state · a repeating loop (PDCA, DevOps) → cycle
- Tasks against calendar time → gantt · task network with estimates and critical path → pert · board columns → kanban · tasks × roles → raci
- Events along a line with annotations → event-line · dated eras and ranges → timeline
- Database tables and relations → er · UML classes → class · git branches and merges → version-control
- Who reports to whom → org · ancestry and unions → family
- Two-axis positioning → quadrant · set overlap → venn · stage-by-stage drop-off → funnel · flows between nodes → sankey
- Hierarchy sized by value → treemap · radiating ideas → mindmap · layered ranks → pyramid
- Geographic regions, points, routes → map · UI layout sketch → wireframe · site/app navigation → sitemap
- Progress toward one target → goal · days until a date → countdown

## Chart types (50)

Each link is the plain-text syntax reference for that one type — a few KB instead of the full spec.

- [journey-map](https://diagrammo.app/llms/journey-map.txt): User experience flow with emotion scores, phases, and annotations
- [c4](https://diagrammo.app/llms/c4.txt): System architecture (context, container, component, deployment)
- [er](https://diagrammo.app/llms/er.txt): Database schemas and relationships
- [class](https://diagrammo.app/llms/class.txt): UML class hierarchies
- [sequence](https://diagrammo.app/llms/sequence.txt): Message request and response interaction flows
- [state](https://diagrammo.app/llms/state.txt): State machine / lifecycle transitions
- [infra](https://diagrammo.app/llms/infra.txt): Infrastructure traffic flow with RPS computation
- [gantt](https://diagrammo.app/llms/gantt.txt): Project scheduling with task dependencies and milestones
- [pert](https://diagrammo.app/llms/pert.txt): Project network with three-point estimates, critical path, and uncertainty (Beta-PERT, Monte Carlo)
- [swimlane](https://diagrammo.app/llms/swimlane.txt): Cross-functional process flow with lanes, phases and gateways (BPMN-style)
- [version-control](https://diagrammo.app/llms/version-control.txt): Git / version-control branch-and-merge graph: commits, branches, merges, rebase, HEAD and remote-tracking (gitGraph-style)
- [timeline](https://diagrammo.app/llms/timeline.txt): Events, eras, and date ranges
- [event-line](https://diagrammo.app/llms/event-line.txt): Annotated narrative timeline — events on a horizontal line with descriptions (not the date-scaled timeline)
- [body](https://diagrammo.app/llms/body.txt): Human anatomy figure annotated by muscle/bone/joint name — for medical, exercise, and educational diagrams
- [org](https://diagrammo.app/llms/org.txt): Reporting hierarchy
- [family](https://diagrammo.app/llms/family.txt): Family tree / genealogy: unions (couples), children, remarriage, adoption, and GEDCOM-style metadata
- [sitemap](https://diagrammo.app/llms/sitemap.txt): Site / app navigation structure
- [bracket](https://diagrammo.app/llms/bracket.txt): Single-elimination tournament bracket: winners auto-advance up a tree; seed the field for a day-0 skeleton or list results for a casual bracket, with two sides mirroring inward to a championship
- [kanban](https://diagrammo.app/llms/kanban.txt): Task board columns
- [raci](https://diagrammo.app/llms/raci.txt): Tasks × roles responsibility matrix with constraint linting
- [tech-radar](https://diagrammo.app/llms/tech-radar.txt): Technology adoption quadrants (adopt/trial/assess/hold)
- [mindmap](https://diagrammo.app/llms/mindmap.txt): Radial hierarchy of ideas branching from a central topic
- [wireframe](https://diagrammo.app/llms/wireframe.txt): Low-fidelity UI layout with panels, controls, and annotations
- [cycle](https://diagrammo.app/llms/cycle.txt): Cyclical process visualization (PDCA, OODA, DevOps loops)
- [pyramid](https://diagrammo.app/llms/pyramid.txt): Stacked hierarchy of layers with descriptions (Maslow, DIKW)
- [ring](https://diagrammo.app/llms/ring.txt): Concentric rings showing nested or hierarchical categories (read core-out)
- [treemap](https://diagrammo.app/llms/treemap.txt): Nested rectangles sized by value — show a hierarchy’s proportions (budgets, disk usage, portfolios) with color by category, value heatmap, or branch
- [block](https://diagrammo.app/llms/block.txt): Block diagram: an author-controlled grid of rectangular blocks with nested, collapsible containers — system/hardware/architecture layouts where the 2-D arrangement is the meaning
- [sketch](https://diagrammo.app/llms/sketch.txt): GUI-first constrained canvas: uniformly-sized shapes placed freely on a snap grid, arrows between them, meaning through tags — the markup is generated by the canvas editor
- [goal](https://diagrammo.app/llms/goal.txt): Single progress-toward-a-target value (now vs target) as a progress bar, thermometer, or gauge — KPIs, fundraising, quotas, completion
- [countdown](https://diagrammo.app/llms/countdown.txt): Live "N days until X" that ticks every second and is accurate on every load — trip dates, launches, deadlines; the only dynamic chart type
- [clock](https://diagrammo.app/llms/clock.txt): Live world-clock board: current time for people/places across time zones, ticking every second, with optional working-hours status and sundown line
- [map](https://diagrammo.app/llms/map.txt): Geographic concept map: highlight/score regions, drop points of interest, connect with routes or edges
- [quadrant](https://diagrammo.app/llms/quadrant.txt): 2x2 positioning matrix
- [venn](https://diagrammo.app/llms/venn.txt): Set overlaps
- [funnel](https://diagrammo.app/llms/funnel.txt): Conversion pipeline
- [slope](https://diagrammo.app/llms/slope.txt): Change between 2 time periods
- [sankey](https://diagrammo.app/llms/sankey.txt): Flow / allocation visualization
- [arc](https://diagrammo.app/llms/arc.txt): Network relationships (linear or circular via `layout`)
- [wordcloud](https://diagrammo.app/llms/wordcloud.txt): Term frequency visualization
- [heatmap](https://diagrammo.app/llms/heatmap.txt): Matrix intensity visualization
- [function](https://diagrammo.app/llms/function.txt): Mathematical expressions
- [bar](https://diagrammo.app/llms/bar.txt): Categorical comparisons for 3 - 5 figures
- [line](https://diagrammo.app/llms/line.txt): Trends over time
- [pie](https://diagrammo.app/llms/pie.txt): Part-to-whole proportions
- [radar](https://diagrammo.app/llms/radar.txt): Multi-dimensional metrics
- [polar-area](https://diagrammo.app/llms/polar-area.txt): Radial bar chart
- [scatter](https://diagrammo.app/llms/scatter.txt): 2D data points or bubble chart
- [flowchart](https://diagrammo.app/llms/flowchart.txt): Decision trees and process flows
- [boxes-and-lines](https://diagrammo.app/llms/boxes-and-lines.txt): General-purpose node-edge diagrams with groups and tags

## MCP tools (registered by `@diagrammo/dgmo-mcp`)

The AI calls these directly; users don't invoke them by name.

- `suggest_chart_type(prompt)`: picks the right chart type from a plain-English prompt
- `render_diagram(dgmo, format, theme, palette)`: renders to SVG or PNG
- `share_diagram(dgmo)`: generates a shareable diagrammo.app URL
- `preview_diagram([{dgmo, title}])`: opens an HTML preview in the browser
- `open_in_app(dgmo)`: opens in the Diagrammo desktop app (macOS)
- `generate_report(title, sections)`: bundles diagrams into an HTML report with a table of contents
- `validate_diagram(dgmo)`: checks syntax without rendering
- `list_chart_types()`: enumerates every supported type
- `get_language_reference(chart_type?)`: returns syntax docs (optionally per type)
- `get_examples(chart_type?)`: pulls curated examples from the gallery

## Context files for non-MCP AI tools

The `@diagrammo/dgmo` npm package ships repo-level context files. Any LLM-backed tool that automatically reads these picks up DGMO syntax rules without extra setup:

- `AGENTS.md` — OpenAI Codex CLI
- `.cursorrules` — Cursor
- `.windsurfrules` — Windsurf
- `.github/copilot-instructions.md` — GitHub Copilot

## Example

```
sequence Login Flow

Browser -POST /login-> AuthService
AuthService -validate-> DB
DB -user-> AuthService
AuthService -200 + JWT-> Browser
```

## Open source

- [github.com/diagrammo/dgmo](https://github.com/diagrammo/dgmo): core library + CLI (MIT)
- [github.com/diagrammo/dgmo-mcp](https://github.com/diagrammo/dgmo-mcp): MCP server (MIT)

## Blog

- [Using DGMO with AI](https://diagrammo.app/blog/dgmo-with-ai): Claude, Codex, Cursor, Copilot
- [DGMO vs Mermaid](https://diagrammo.app/blog/mermaid-vs-dgmo)
- [Diagrams as code](https://diagrammo.app/blog/diagrams-as-code)
- [Infrastructure diagram guide](https://diagrammo.app/blog/infrastructure-diagram-guide)
- [Sequence diagram tutorial](https://diagrammo.app/blog/sequence-diagram-tutorial)

## FAQ

**Is it free?** Yes. Every surface is free. The CLI and npm library are open-source (MIT).

**Does it work offline?** Desktop app and CLI work fully offline.

**File format?** Plain `.dgmo` text files — no binary formats, no vendor lock-in.

**How is it different from Mermaid?** Simpler syntax, richer infrastructure and sequence diagram support, native desktop app with click-to-source navigation, consistent theming across all chart types. See https://diagrammo.app/compare.

**Can AI assistants use it?** Yes — `dgmo --install-claude-code-integration` (or the Codex / Claude Desktop equivalents) sets up an MCP server that the AI calls directly. See https://diagrammo.app/ai.

## Optional

- [Homepage](https://diagrammo.app)
- [Get Started picker](https://diagrammo.app/start): pick browser, Mac, AI, or code path
- [Terms](https://diagrammo.app/terms)