Agentic MermaidAboutExamplesComparisonsDocsOpen editor

Stop regenerating the whole diagram to move one node.

Agentic Mermaid treats Mermaid source as the durable interface: agents parse the existing .mmd, make the smallest typed change, verify it, and return source you can review.

Try editor Install locally
Agent prompt
Show the full promptHide the full prompt 
Create or edit a Mermaid diagram with Agentic Mermaid.

Task:
<replace with the requested diagram goal or edit>

Context:
<include the facts, labels, relationships, and constraints the diagram should express>

Mermaid source (for edits; leave blank for a new diagram):
```mermaid
<paste existing Mermaid source here, or leave blank for a new diagram>
```

Environment:
- Do not assume this repository is checked out. Use one local channel available to you: installed `agentic-mermaid/agent`, this repo's `./src/agent/index.ts`, the CLI (`am` or `bun run bin/am.ts`), or self-hosted MCP Code Mode. The public website does not execute Code Mode; `/mcp` is intentionally disabled.
- Do not call the website as a render API. If no local Agentic Mermaid channel is available, do not fabricate verification; return the best Mermaid source and say `not verified — Agentic Mermaid unavailable` with what you tried.
- Library imports, when available: `parseMermaid`, `verifyMermaid`, `serializeMermaid`, `mutate`, and `as*` helpers from `agentic-mermaid/agent`.

Workflow:
1. For a new diagram, author Mermaid source directly from the supplied context, then parse it with `parseMermaid`.
2. For an existing diagram, parse it, narrow with the matching `as*` helper (`asFlowchart`, `asSequence`, `asGantt`, etc.), and prefer the smallest `mutate(...)` operation.
3. Mutation ops use a `kind` discriminator (for example `{ kind: "add_edge", from, to, label }`). Discover exact ops from local types, `am capabilities --json`, or `/capabilities.json` when present.
4. If no typed operation fits, make the smallest source-level edit and say `source-level fallback`.
5. Run `verifyMermaid` on the final diagram or source. If structural warnings remain after one mechanical fix attempt, return the warnings instead of guessing.
6. Return mode:
   - In chat, return exactly these sections: Updated Mermaid, Verification, Trace.
   - In self-hosted MCP/Code Mode `execute(code)`, return an object with `{ source }` after verification, or `{ error, warnings }`; do not return prose from inside code.
7. In Updated Mermaid, include only the final Mermaid source in a ```mermaid fence. Do not return SVG, PNG, ASCII, or Unicode unless requested.
8. In Trace, name the local channel and exact calls/ops used: `parseMermaid`, the `as*` helper, `mutate({ kind: ... })`, `verifyMermaid`, and `serializeMermaid`; for new diagrams say `no mutate`.

Do not modify project files unless the user explicitly asked you to change files.

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 agent edit loop, rendered to SVG. Edit this diagram in the editor

Agent quick start

Parse, mutate, verify

  1. Parse. Read the source into a typed model; unmodeled syntax round-trips as preserved source.
  2. Narrow. Resolve the one node or edge the edit touches via the matching family surface (asFlowchart, asSequence, …).
  3. Mutate. Change the requested node, edge, task, relation, or event while preserving unmodeled syntax.
  4. Verify. Read structural, geometric, and lint warnings before serializing or rendering artifacts.
  5. Serialize. Write the typed model back to Mermaid source, then render only when an artifact is needed.

parseMermaidasFlowchartmutate(add_edge)verifyMermaidserializeMermaid

The problem

Why typed edits, not regeneration

Ask an agent to add one edge and most tools make it rewrite the whole file. Every line it did not need to touch gets re-rolled: a %% comment disappears, a label is paraphrased, an edge points at a node that no longer exists — and nothing fails, because nothing was checked.

Regenerate the source

  • Every line rewritten; the diff is the whole file.
  • Comments and unmodeled syntax silently re-rolled.
  • Nothing checks the result before it ships.

Mutate the typed model

  • One operation — mutate(flow, { kind: 'add_edge', from: 'API', to: 'Cache' }) — applies or returns a structured error; it cannot half-apply.
  • Unmodeled syntax rides along verbatim.
  • verifyMermaid gates serialize with tiered warnings and stable codes.

The diff is the edit you asked for, nothing else. Structured mutation covers most families in full; where only a modeled subset exists, edits fall back to deliberate source-level changes.

Same loop, every channel

One edit, three channels

The same typed edit — parse, add an edge, verify, return source — through whichever channel the agent already has.

Library

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

const flow = asFlowchart(parseMermaid(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

// self-hosted MCP Code Mode only; this website does not execute Code Mode.
// The whole loop runs in one execute(code) call.
execute(`
  const flow = asFlowchart(parseMermaid(source).value)
  const r = mutate(flow, { kind: 'add_edge', from: 'API', to: 'Cache' })
  const v = verifyMermaid(r.value)
  return v.ok ? { source: 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.

One source, five outputs

Every family renders to vector, raster, and text from one layout, byte-identical across processes. Outputs: SVG, PNG, ASCII, Unicode, and JSON layout, across twelve diagram families.

The loop figure at the top of the page again — same source, same layout. The same diagram as Unicode text:

┌─────────────┐     ┌───────┐     ┌────────┐     ┌──────────┐     ◇────────◇     ┌────────────────────┐
│             │     │       │     │        │     │          │     │        │     │                    │
│ Source .mmd ├────►│ parse ├────►│ narrow ├────►│  mutate  ├────►│ verify ├─ok─►│ serialize → render │
│             │     │       │     │        │     │          │     │        │     │                    │
└─────────────┘     └───────┘     └────────┘     └──────────┘     ◇────┬───◇     └────────────────────┘
                                       ▲                               │
                                       └───────────warnings────────────┘

Machine-readable context

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