# DGMO AI Integration Guide Use AI coding tools to generate `.dgmo` diagrams. This guide covers Claude Code, Copilot, Cursor, Windsurf, and any tool with an MCP client. --- ## One-step setup (recommended) Install the `dgmo` CLI, then run one command: ```bash brew install diagrammo/dgmo/dgmo # or: npm install -g @diagrammo/dgmo-cli dgmo install # auto-detects every AI assistant you have ``` `dgmo install` with **no target** scans for Claude Code, Codex, Claude Desktop, Cursor, Windsurf, and Copilot, then configures each one non-interactively — no prompts, no second package to install. The only binary you ever need is `dgmo`; it provides the MCP server through its own `dgmo mcp` subcommand. Target a single assistant, or pick a scope, when you want to: ```bash dgmo install claude-code # just one surface dgmo install codex --scope project # write config into the current repo dgmo install --dry-run # preview every change, write nothing ``` For Claude Code this copies the `/dgmo` skill into `~/.claude/commands/` (full dgmo context — all chart types, CLI flags, workflow, and tips) and adds the MCP server to `~/.claude/settings.json`. Restart the assistant afterward. **Keeping it current:** - **Homebrew** bundles the MCP server, so `brew upgrade dgmo` upgrades the CLI *and* the server together. Re-run `dgmo install` afterward only to refresh the **skill files** (those are copies in your home dir). - **npm global**: a plain `dgmo` upgrade doesn't touch the server or skill copies — re-run `dgmo install`, which overwrites the skills and upgrades the server to the latest. - Either way, `DGMO_MCP_LATEST=1` in the environment makes `dgmo mcp` always fetch the newest server at launch (network round-trip on start), so it's never stale. --- ## Manual MCP configuration `dgmo install` is the easy path. To wire the MCP server by hand, point any MCP client at the `dgmo` binary's `mcp` subcommand: ```json { "mcpServers": { "dgmo": { "command": "dgmo", "args": ["mcp"] } } } ``` **Tools:** `check_app_installed`, `suggest_chart_type`, `get_language_reference`, `get_examples`, `validate_diagram`, `open_in_app`, `share_diagram`, `render_diagram`, `preview_diagram`, `generate_report`, `list_chart_types`. `dgmo mcp` execs the installed server, or fetches it on demand via `npx` if it isn't installed yet — so no separate `dgmo-mcp` step is required. (If you'd rather not install the CLI at all, `{ "command": "npx", "args": ["-y", "@diagrammo/dgmo-mcp"] }` still works.) See `dgmo-mcp/README.md` for full options. Output default is app-aware: `check_app_installed` decides it — when the Diagrammo desktop app is installed, the diagram source is saved and opened live in the app (`open_in_app` with the saved file path); otherwise an online share URL is opened. A PNG/SVG is rendered only when the user explicitly asks. --- ## Claude Code — CLAUDE.md snippet To teach Claude about DGMO in a specific project without the global skill, paste the generated core below into your `CLAUDE.md`. It is the same single-sourced anti-patterns + 43-type index that every DGMO AI surface carries (see "How the AI core is generated"). Render with `dgmo file.dgmo` (PNG) or `dgmo share file.dgmo` (shareable link); full per-type syntax lives in `node_modules/@diagrammo/dgmo/docs/language-reference.md`. ## DGMO AI Core _Generated from `language-reference.md` — the anti-patterns and 50-type index below are identical across every DGMO AI surface._ ### Disambiguation — where DGMO diverges from LLM priors LLMs default to Mermaid / PlantUML habits; DGMO differs. These rules prevent the most common parse errors: - **No colons in declarations, directives, tags, or data rows.** `bar Revenue` (not `bar: Revenue`); `series Cloud blue, Legacy red` (not `series: ...`); `North 850` (not `North: 850`); `tag Team as t` (not `tag: Team`). A colon binds a value only in metadata (`key: value`), class/function type separators, and a few scoped spots — see §26. - **No Mermaid arrow-labels.** Put the label _between_ the dashes: `A -Login-> B`, never `A -> B: Login`. Sequence: `->` sync, `~>` async; left-to-right only — no `<-` / `<~`. - **No indented edges on a map.** Every map connection is ONE full line — `JFK ~daily~> LAX`; for a hub repeat the origin per spoke (`JFK ~daily~> LHR`, …). A bare source with indented `-> dest` legs errors as `Malformed edge`; indented legs are valid ONLY inside a `route` block (an ordered stop→stop voyage). Edge endpoints auto-create their POIs — don't add separate `poi` lines for places already in an edge. - **No `|` metadata delimiter** (removed 0.18.0; since 0.43.0 a stray `|` raises no dedicated error — it falls through as a literal). Use same-line `Name key: value, k2: v2` or indented `key: value`. (`|` survives only in wireframe `{A | B}` dropdowns, in-arrow label text, and quoted names.) - **No removed participant keywords.** Do not write `X is a service` / `external` / `frontend` / `networking` / `gateway` — these were removed and error. A bare name renders the default shape; for a typed glyph use `is a person` / `is a database` / `is a queue`. - **Colors are a closed set of EXACTLY these 11 — nothing else is a color.** Valid colors, the complete list: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `teal`, `cyan`, `gray`, `black`, `white`. That is the entire universe of DGMO colors — there are no others. Do NOT use hex (`#1f77b4`), `rgb(...)`, `hsl(...)`, or ANY CSS color name: `crimson`, `royalblue`, `navy`, `pink`, `lime`, `magenta`, `indigo`, `gold`, `salmon`, `turquoise`, `violet`, etc. are ALL invalid — they are rejected and the element falls back to an auto-assigned color. When you want a color outside the 11, map it to the nearest one: crimson/scarlet→`red`, royalblue/navy/cobalt→`blue`, pink/magenta/violet/indigo→`purple`, lime/olive→`green`, gold/amber→`yellow`, turquoise→`teal`. Apply a color as a trailing token (`Done green`) or after a category/group bracket (`[North America] red`). Named colors are mandatory because they re-resolve per active palette + light/dark theme; a hardcoded value never would. - **Show-everything is the default.** Every label / value / percent renders by default. Emit `no-name` / `no-value` / `no-percent` / `no-*` ONLY when the user explicitly asks to hide something — never defensively. - **`//` comments only** (never `#`). **Indentation closes blocks** — never `end`. - **Declare before reference.** An edge target must be declared on a prior line; put metadata and edges on/under one declaration to avoid `Duplicate node` warnings. - **No reference scaffolding in output.** Emit only DGMO source. This doc is organized with HTML-comment anchors (the `TYPE`, `TIPS`, and `AI-CORE` markers, each wrapped in comment delimiters); never copy any such `` comment into a diagram. They mark sections of the docs, not DGMO syntax; the parser flags a stray HTML comment as an `Unexpected line` warning. (DGMO's only comment form is `//`.) Two traps in the _other_ direction (DGMO wants a colon / a space where you might not expect): - **Infra node properties REQUIRE the colon** — `cache-hit: 80%`, `instances: 3`, `max-rps: 8000`, `latency-ms: 45`. But top-level infra **options** are space-separated (`default-rps 100`). Don't conflate them. - **ER columns are space-separated** — `id int pk`, `email varchar` (the one SQL-DDL carve-out; everything else indented-typed uses a colon). Idiomatic example — color via tags, metadata on the declaration line, indented edges: ```dgmo boxes-and-lines Service Map tag Team as t Platform blue Product green active-tag Team API Gateway t: Platform -routes-> Orders -routes-> Billing Orders t: Product Billing t: Product ``` ### Make it look good — authoring guidance Valid markup is the floor, not the goal. A good diagram reads at a glance. Apply these unless the prompt says otherwise: - **Always title it.** Every diagram gets a short title on the type-declaration line (`flowchart Checkout Flow`, `sequence Checkout`, `boxes-and-lines Service Map`) so it is self-describing — never leave the bare type keyword alone. Infer a fitting title from the request when the user gives none. - **Categorize and color — by default, not only when obvious.** Before drawing, find the axis that sorts the items into kinds and color by it: layer (frontend / backend / data), role (client / service / datastore), trust zone (internal / external / third-party), status (done / active / blocked), owner/team, or read-path vs write-path. Almost every diagram has such an axis — actively look for one rather than leaving everything monochrome. Express it with a **tag group**, never ad-hoc per-node colors: declare `tag as t` (the name is a single word — `tag TrustZone as tz` — or quote a multi-word name: `tag "Trust Zone" as tz`), indent the category values (a trailing color is optional — bare values auto-pick a palette color), set `active-tag `, then assign each item `Node t: ` (see the tag-group syntax in the per-type section below). Only the 11 named palette colors exist, and they re-resolve per palette/theme. Color the grouping so the categories — and the boundaries between them — read at a glance. **Buckets, not name tags — never 1:1.** A tag group must have _fewer_ values than it has members: each color should bucket two or more items so the palette compresses the diagram into a few meaningful kinds (aim for ~2–4 categories, and keep distinct colors well under half the item count). If you find yourself giving nearly every item its own value, you've enumerated, not categorized — merge the singletons up a level until each color groups at least two (a `cache` and a `database` are both `datastore`; a caller and a gateway are both `client`; two microservices are both `service`). One color per item is the same visual noise as random colors — the grouping only earns its place when a color means "these belong together." Leave items uncolored only when they genuinely form a single undifferentiated kind, or the user asked for no color. - **Keep labels short.** A few words per node. Move detail into notes or metadata, never a full sentence inside a label. - **Let the defaults show.** Don't add `no-*` opt-outs unless the user asked to hide or disable something — they strip helpful labels, values, and color. - **Pick a fitting direction.** Top-to-bottom for hierarchies and processes; left-to-right for pipelines and flows (where the type supports a direction). ### Chart-type index (45) — pick the type, then fetch its section | id | when to use | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sequence` | message / interaction flows over time | | `flowchart` | decision trees and process flows | | `state` | state-machine / lifecycle transitions | | `class` | UML class hierarchies | | `er` | database schemas and relationships | | `c4` | system architecture (context / container / component / deployment) | | `infra` | infrastructure traffic flow with RPS computation | | `boxes-and-lines` | general-purpose node-edge diagrams with groups and tags | | `sitemap` | site / app navigation structure | | `mindmap` | radial hierarchy of ideas from a central topic | | `org` | reporting hierarchy | | `family` | family tree / genealogy: unions (couples), children, remarriage, adoption, GEDCOM-style metadata | | `bracket` | single-elimination tournament bracket: winners auto-advance; seed the field for a day-0 skeleton or list results casually; two sides mirror to a championship | | `kanban` | task-board columns | | `gantt` | project scheduling with task dependencies and milestones | | `pert` | project network with three-point estimates and critical path | | `swimlane` | cross-functional process flow with lanes, phases and gateways (BPMN-style) | | `version-control` | git / version-control branch-and-merge graph: commits, branches, merges, rebase, HEAD and remote-tracking (gitGraph-style) | | `timeline` | events, eras, and date ranges | | `event-line` | annotated narrative timeline — events on a line with descriptions, optionally not to scale (NOT the date-scaled `timeline`) | | `body` | human anatomy figure annotated by muscle name — for medical, exercise, and educational diagrams | | `journey-map` | UX flow with emotion scores, phases, annotations | | `cycle` | cyclical process (PDCA, OODA, DevOps loops) | | `raci` | tasks × roles responsibility matrix; variant (RACI / RASCI / DACI) is inferred from the markers used | | `tech-radar` | technology adoption quadrants (adopt / trial / assess / hold) | | `quadrant` | 2×2 positioning matrix | | `pyramid` | stacked hierarchy of layers (Maslow, DIKW) | | `ring` | concentric rings of nested categories | | `treemap` | nested rectangles sized by value (budgets, disk usage, portfolios) | | `block` | author-controlled grid of nested, collapsible blocks (system / architecture layouts) | | `sketch` | GUI-first free-placement canvas: uniform shapes on a snap grid, arrows, tags (markup is app-generated) | | `goal` | single progress-toward-a-target value (`now` vs `target`) as a progress bar, thermometer, or gauge — KPIs, fundraising, quotas | | `countdown` | 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` | live world-clock board: current time for people/places across time zones, ticking every second, with optional working-hours status and sundown line | | `map` | geographic concept map: regions, points, routes | | `wireframe` | low-fidelity UI layout with panels and controls | | `bar` | categorical comparisons (multi-series via `stack` / `group`) | | `line` | trends over time (multiple series via a `series` block; filled via `fill`; dual y-axes via `y-label` / `y-right-label`) | | `pie` | part-to-whole proportions (ring/doughnut via `hole`) | | `radar` | multi-dimensional metrics | | `polar-area` | radial bar chart | | `scatter` | 2D points or bubble chart | | `heatmap` | matrix intensity | | `funnel` | conversion pipeline | | `sankey` | flow / allocation | | `arc` | network relationships (linear, or circular via `layout chord`) | | `slope` | change between two periods | | `venn` | set overlaps | | `wordcloud` | term-frequency | | `function` | mathematical expressions (colon required: `f(x): x^2`) | **Need more than the index gives you?** Fetch the per-type section: MCP `get_language_reference(type)` / `get_examples(type)`, or read that type's section below. The `suggest_chart_type` tool returns the chosen type's section automatically. **When the type isn't obvious, ask — don't guess.** Call `suggest_chart_type` first. If it returns an `⚠️ ASK THE USER` directive (the request is ambiguous between candidates, or nothing matched), present those candidate options to the user and wait for their pick before generating — never silently choose. A confident result (high/medium) you can proceed with. ### Common examples (curated, parse-clean) _The most common types, inline so you can generate them without a fetch. For the other 42, get the per-type section (see below)._ #### journey-map ```dgmo journey-map A Cabin Boy's First Voyage persona Squidlips Sam color: blue Greenhorn cabin boy, first time at sea Sworn to the crew but quietly terrified [Signing On] Sign the articles score: 4, emotion: Hopeful description: Captain reads the code aloud — pay shares, no women aboard, lights out at 8 [The Tempest] Caught in a squall off the reef score: 1, emotion: Terrified pain: Two crewmates lost overboard before dawn thought: Maybe the merchant fleet wasn't so bad after all Dawn, and she still floats score: 3, emotion: Relieved [The Prize] Strike the colors score: 5, emotion: Triumphant description: Heavy with silver from the Veracruz mines [Homecoming] Bury a share on the island score: 5, emotion: Proud thought: Three doubloons hidden where only he can find them Back to the Rusty Anchor score: 4, emotion: Content opportunity: Next time he signs on as a full hand, not a boy ``` #### c4 ```dgmo c4 Pirate Treasure Map System tag Scope as sc Crew blue External gray Captain is a person description: Commands the fleet and plans raids TreasureMap is a system description: Tracks buried treasure locations and raid intelligence -Views treasure locations-> Captain -Sends raid alerts [carrier pigeon]-> Lookout containers ChartRoom is a container description: Interactive sea chart with treasure markers, tech: Parchment -Queries treasure data [secret code]-> Vault Vault is a container description: Encrypted treasure ledger and coordinates, tech: Iron Chest -Reads/writes [quill and ink]-> TreasureLog TreasureLog is a container description: "Stores locations, guard counts, and loot inventories", tech: Leather-Bound Tome Lookout is an external description: Crow's nest spotter on allied ships, sc: External ~Relays sightings to~> Captain deployment Flagship container ChartRoom container Vault SecretCave container TreasureLog ``` #### er ```dgmo er Pirate Fleet ships id int pk name varchar ship_type varchar cannons int 1-aboard-* crew_members 1-1 captains 1-carries-* treasure captains id int pk name varchar ship_id int fk bounty int ?-frequents-1 ports *-has-1 crew_members crew_members id int pk name varchar ship_id int fk role varchar nullable treasure id int pk name varchar value int ship_id int fk nullable ports id int pk name varchar region varchar unique 1-docks-* ships ``` #### class ```dgmo class Ship Class Hierarchy interface Vessel + sail(): void + anchor(): void abstract Ship implements Vessel # name: string # crew: number + getName(): string Galleon extends Ship - cannons: number + fire(): void Sloop extends Ship - speed: number + flee(): void enum ShipType Galleon Sloop Frigate Ship -> ShipType has type ``` #### sequence ```dgmo sequence Treasure Hunt App tag Concern as c Search blue Claims green Notifications orange User is an actor [Treasure Service] TreasureAPI MapDB is a database NotifyQueue is a queue User -Search nearby loot-> WebApp WebApp -GET /treasures?nearby-> TreasureAPI c: Search TreasureAPI -Find within 5nm-> MapDB c: Search note - check location - use compass MapDB -3 results-> TreasureAPI TreasureAPI -locations-> WebApp WebApp -Show treasure map-> User == Claim == User -Claim chest #42-> WebApp WebApp -POST /claim-> TreasureAPI c: Claims if chest available TreasureAPI -Set status = claimed-> MapDB c: Claims MapDB -OK-> TreasureAPI TreasureAPI ~treasure.claimed~> NotifyQueue c: Notifications TreasureAPI -Claim accepted-> WebApp WebApp -500 doubloons earned!-> User else TreasureAPI -409 Already claimed-> WebApp WebApp -Too slow, matey!-> User ``` #### state ```dgmo state Ship Battle Lifecycle [*] -> Sailing Sailing -enemy spotted-> BattleStations [Losses] gray Captured -> [*] Sinking -> [*] [Aftermath] teal Victorious -loot taken-> Sailing Retreating -escaped-> Sailing -caught-> Captured [Combat] red Engaging -alongside-> Boarding -hull breach-> Sinking -outgunned-> Retreating Boarding -crew wins-> Victorious -crew loses-> Captured BattleStations -in range-> Engaging -enemy retreats-> Sailing ``` #### infra ```dgmo infra Pirate Communication Network tag Fleet as f Blackbeard red Bonny purple Rackham blue Edge rps: 200 -> SignalFlags SignalFlags f: Blackbeard description: Flag semaphore relay — ship-to-ship messaging latency-ms: 30000 -> Flagship -> ScoutShip Flagship f: Blackbeard description: Command vessel — decrypts and routes all intelligence instances: 1 max-rps: 50 latency-ms: 5000 -> CarrierPigeons -> RumRunner ScoutShip f: Bonny description: Fast sloop for reconnaissance instances: 2 max-rps: 30 latency-ms: 8000 -> Flagship CarrierPigeons f: Rackham description: Long-range bird relay — messages to allied ports buffer: 100 drain-rate: 12 retention-hours: 72 -> TavernNetwork [Allied Ports] instances: 3 TavernNetwork f: Rackham description: Dockside tavern informants across the Caribbean max-rps: 20 latency-ms: 86400000 RumRunner f: Bonny description: Smuggler supply line — moves coded messages in rum barrels concurrency: 4 duration-ms: 172800000 -> TavernNetwork ``` #### gantt ```dgmo gantt Blackbeard's Blockade — 1718 start-date 1718-05-01 today-marker 1718-05-15 tag Role as r Command red Crew blue Captives orange marker 1718-05-14 Ransom Deadline red era 1718-05-08 -> 1718-05-17 Blockade Active blue [Preparation] r: Command Provision Ship 3d r: Crew, progress: 100 -> Anchor Fleet 2d r: Crew, progress: 100 Scout Harbor 3d r: Crew, progress: 100 -> Position Cannons 3d r: Crew, progress: 100 Recruit Hands 5d r: Crew, progress: 100 +7d [Blockade] r: Crew Seize Merchants 4d progress: 100 -> Hold Hostages 5d r: Captives, progress: 60 Patrol Perimeter 9d progress: 75 Demand Medicine 4d r: Command, progress: 100 -> Threaten Executions 3d? r: Command, progress: 90 +17d [Resolution] r: Command Receive Ransom 2d r: Captives -> Release Prisoners 1d r: Captives -> Set Sail 0d Burn Evidence 2d r: Crew ``` **Fetch more:** call `get_language_reference(type)` for a type's full syntax and `get_examples(type)` for starter templates. `suggest_chart_type` returns the chosen type's reference automatically. --- ## Other AI Tools — Prompt Files (generated artifacts) DGMO ships context files for popular AI coding tools, included in the npm package and auto-loaded when present in a project root. **These files are generated** — their shared DGMO AI core (the anti-patterns block + 43-type index) is emitted from `docs/language-reference.md` by `scripts/gen-ai-core.mjs`. Never hand-edit the region between the `DGMO-AI-CORE` markers; it is overwritten on every regeneration. | File | Tool | How it works | |------|------|-------------| | `.github/copilot-instructions.md` | GitHub Copilot | Auto-loaded in repos with this file | | `.cursorrules` | Cursor | Auto-loaded when present in project root | | `.windsurfrules` | Windsurf | Auto-loaded when present in project root (byte-identical to `.cursorrules`) | The easiest way to set these up is `dgmo install` — it does the right thing per tool: ```bash dgmo install cursor # wires MCP (~/.cursor/mcp.json) + drops .cursorrules dgmo install windsurf # wires MCP (~/.codeium/windsurf/mcp_config.json) + .windsurfrules dgmo install copilot # writes ./.github/copilot-instructions.md (Copilot has no MCP) ``` Cursor and Windsurf speak MCP, so `dgmo install` gives them the full render/share tools (pointed at `dgmo mcp`), plus the inline rules file. Copilot is guidance-only. `dgmo install` with no target also writes Copilot's file automatically when the current repo has a `.github` directory. To set the context files up by hand instead: ```bash # From node_modules (if installed as a dependency) cp node_modules/@diagrammo/dgmo-cli/.cursorrules . cp node_modules/@diagrammo/dgmo-cli/.windsurfrules . mkdir -p .github && cp node_modules/@diagrammo/dgmo-cli/.github/copilot-instructions.md .github/ # From global npm install cp $(npm root -g)/@diagrammo/dgmo-cli/.cursorrules . ``` Each file contains the generated DGMO AI core (anti-patterns + 43-type index), a condensed syntax reference with examples, rendering commands, and common mistakes to avoid. --- ## How the AI core is generated DGMO uses **progressive disclosure** across three tiers so AI surfaces stay small and never drift: - **Tier 0 — universal core** (`docs/language-reference.md` → `` + ``). `scripts/gen-ai-core.mjs` extracts these and writes them, with a generated-file banner, into the `DGMO-AI-CORE` region of `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md`, `SKILL.md`, and this guide. Edit the source blocks in `language-reference.md`; never the generated regions. - **Tier 1 — per-type section**, fetched on demand: MCP `get_language_reference(type)` slices the reference on `` anchors (and `suggest_chart_type` returns the chosen type's section automatically), or read the type's section directly. - **Tier 2 — exhaustive grammar**: `docs/dgmo-language-spec.md` (workspace root) for deep/edge questions. Regeneration runs inside `sync-language-ref.sh`; a Vitest gate parses every emitted ```dgmo fence so no stale syntax can ship. --- ## Rendering commands ```bash dgmo diagram.dgmo # PNG output dgmo diagram.dgmo -o output.svg # SVG output dgmo share diagram.dgmo # Shareable diagrammo.app URL (copied to clipboard) dgmo share diagram.dgmo --no-copy # Print URL without touching the clipboard dgmo types # List all supported chart types dgmo types --json # Machine-readable chart type list ``` --- ## Supported chart types Run `dgmo types` for the full, authoritative list, call the MCP `list_chart_types` tool, or see the 43-type index in `docs/language-reference.md` (§0 AI Core). The list is intentionally not duplicated here — it drifts every time a chart type is added.