Agentic Mermaid
Menu

Beautiful diagrams, made with your agent.

Try editor Install locally

watercolor · paper — Flowchart (1/9)

Open in editor

watercolor · paper — Flowchart

Flowchart in Watercolor and PaperBuild-time render: Checkout service — same source as the previous slide, style watercolor, palette paper, seed 4. Client Services Data Web app API gateway Auth Catalog Orders Queue Fulfilment worker Sessions Cache Postgres

Agent quick start

Prompt, style, verify

  1. Describe the diagram. Ask for an architecture map, product flow, timeline, Gantt plan, or sequence.
  2. Pick style and palette. Use a built-in style such as watercolor, blueprint, or publication-figure, then add a palette such as paper or nord-light.
  3. Let the agent edit. Existing diagrams go through typed mutation; new diagrams start as Mermaid source and then get checked.
  4. Verify before export. Render SVG or PNG only after warnings are read and the source still says what you asked for.

parseRegisteredMermaidasFlowchartmutate(add_edge)verifyMermaidserializeMermaid

Agentic Mermaid edit loop Source flows through parse, narrow, mutate, verify, and serialize to render, with warnings routed back for another edit. ok warnings Source .mmd parse narrow mutate verify serialize → render
The loop the agent runs: parse, narrow, mutate, verify, serialize.

Polished output, deterministic source, agent-safe edits.

Agentic Mermaid combines a Mermaid parser, deterministic renderer, style system, and verification loop. Your agent can create a diagram, apply a style and brand palette, export the artifact you need, and keep the Mermaid source reviewable for the next edit.

Beautiful renders

  • Built-in styles cover docs, decks, reports, terminals, sketches, and blueprints.
  • Palette themes and custom JSON styles encode brand colors, typography, strokes, fills, and page backdrops.
  • SVG and PNG serve pages and decks; ASCII, Unicode, and layout JSON serve review tools and agents.

Agent-native control

  • Typed parse and mutate helpers make Mermaid source the durable interface.
  • verifyMermaid reports structural, geometric, and lint warnings with stable codes.
  • start.md, CLI, library, and MCP surfaces give agents one tested operating path.

The result is source you can review, renders you can ship, and an edit loop your agent can repeat.

One request, three channels

Ask the agent to make the diagram, set style and palette, verify the source, and return the render path through whichever channel it already has.

Library

import { parseRegisteredMermaid, asFlowchart, mutate, verifyMermaid, serializeMermaid }
  from 'agentic-mermaid/agent'

const flow = asFlowchart(parseRegisteredMermaid(source).value)
const r = mutate(flow, { kind: 'add_edge', from: 'API', to: 'Cache' })
if (!verifyMermaid(r.value).ok) throw new Error('edit left structural warnings')
const next = serializeMermaid(r.value)

CLI

$ am mutate diagram.mmd --op '{"kind":"add_edge","from":"API","to":"Cache"}'
# applies the op, verifies, emits source
$ am verify diagram.mmd --json            # tiered warnings, stable codes
$ am render diagram.mmd --format unicode  # same layout, in the terminal

MCP

// MCP Code Mode: the hosted MCP at https://agentic-mermaid.dev/mcp, or a self-hosted server.
// The whole loop runs in one execute(code) call; the SDK is bound as `mermaid`.
execute(`
  const source = 'flowchart LR\n  UI[Web app] --> API\n  API --> DB[(Postgres)]'
  const flow = mermaid.asFlowchart(mermaid.parseRegisteredMermaid(source).value)
  const r = mermaid.mutate(flow, { kind: 'add_edge', from: 'API', to: 'Cache' })
  const v = mermaid.verifyMermaid(r.value)
  return v.ok ? { source: mermaid.serializeMermaid(r.value) }
              : { error: 'verify failed', warnings: v.warnings }
`)

In the cloned repo, am is bun run bin/am.ts; MCP wiring is in Getting started.

Install locally in Getting started: clone, build, and wire the stdio MCP in two minutes.

Style × palette

One source, three styles

Render SVG for docs, PNG for decks, ASCII or Unicode for review, and layout JSON when tooling needs coordinates. To change visual treatment, pass a style stack in render options; examples include watercolor,paper and ops-schematic,nord-light. Seed changes only sketch noise; node positions and edge routes stay fixed.

See all style/palette examples

Each card uses the same Mermaid source with different render options. Agents pass style, palette, and seed in the render call instead of rewriting labels or edges for visual changes.

Sketch note diagram in Watercolor and PaperThe same Mermaid source rendered with watercolor, paper, and seed 4. yes no Pull request CI green? Deploy to staging Agent fixes tests Smoke checks Release

Sketch note

For whiteboards, docs drafts, and agent working notes.

  • Stylewatercolor
  • Palettepaper
  • Seed4
Open this style
Report figure diagram in Report Figure and GitHub LightThe same Mermaid source rendered with publication-figure, github-light, and seed 0. yes no Pull request CI green? Deploy to staging Agent fixes tests Smoke checks Release

Report figure

For specs, READMEs, and reviewable product documents.

  • Stylepublication-figure
  • Palettegithub-light
  • Seed0
Open this style
Ops map diagram in Compact Trace Map and Nord LightThe same Mermaid source rendered with ops-schematic, nord-light, and seed 8. YES NO PULL REQUEST CI GREEN? DEPLOY TO STAGING AGENT FIXES TESTS SMOKE CHECKS RELEASE

Ops map

For traces, runbooks, and compact engineering diagrams.

  • Styleops-schematic
  • Palettenord-light
  • Seed8
Open this style

Machine-readable context

Most agents only need the prompt. When they need durable context, keep the set small and tested.