About Agentic Mermaid
Agentic Mermaid is a fork of beautiful-mermaid, aimed at a job the original did not have: programs that draw and check diagrams with no person watching. It renders without a browser, reports its own layout errors, and edits diagrams as a typed tree.
An agent writes a diagram it cannot see
When a coding agent emits a Mermaid block, it is working blind. mermaid.js renders in a browser, so the only way to know whether an edge landed on the right node, or whether two boxes overlap, is to start a headless Chrome, rasterize, and look at the picture. An agent in the middle of a task has no picture to look at, so the diagram ships and the break surfaces when a person opens the page. Agentic Mermaid takes the browser out of the path and hands the agent something it can read instead.
The same source renders the same way
The layout is a pure function of the source and the theme tokens. Render twice and the geometry is byte-identical, on any machine, with nothing measuring text in a browser. Because the bytes are stable, a rendered SVG can be committed and diffed in review, a PNG can be cached by the hash of its source, and a render can gate a CI job without flaking. mermaid.js holds none of this: its layout moves between versions and depends on the browser doing the measurement.
am render diagram.mmd --format svg > a.svg
am render diagram.mmd --format svg > b.svg
diff a.svg b.svg # no output: identical bytes, every run, no browserVerify before you serialize
verifyMermaid reads a parsed diagram and sorts its warnings into three tiers. Structural warnings mean the diagram is wrong: an edge anchored to nothing (EDGE_MISANCHORED), a node off the canvas (OFF_CANVAS), content that escaped its group (GROUP_BREACH). Geometric warnings mean it reads but the routing is poor: overlapping nodes (NODE_OVERLAP), a path that crosses itself (ROUTE_SELF_CROSS). Lint warnings cover cleanliness and round-trip loss. Every warning carries a stable code, so an agent runs verify the way it runs a test: check, read the code, fix, check again. The editor shows the same three tiers as you type, am verify prints them, and the MCP server returns them.
const verify = verifyMermaid(parsed.value)
if (!verify.ok) throw new Error(JSON.stringify(verify.warnings, null, 2))
// every warning: a code (EDGE_MISANCHORED), a tier (structural | geometric | lint),
// and a severity, so the fix is mechanicalEdits go through a typed tree
To add an edge with a string-based tool, you append a line and hope it parses. Agentic Mermaid parses the source into a typed tree, narrows it to a family with asFlowchart, applies one operation, and serializes back. The operation matches a known shape or returns an error, so it cannot half-apply and leave the source corrupt. Syntax the library cannot narrow is preserved verbatim, and a lossy change asks first.
const flow = asFlowchart(parseMermaid(source).value) // narrow to flowchart
const r = mutate(flow, { kind: 'add_edge', from: 'API', to: 'Cache' })
if (!verifyMermaid(r.value).ok) throw new Error('mutation left it broken')
const next = serializeMermaid(r.value) // typed tree back to textOne source, five surfaces
The same parsed diagram serializes to SVG for a web page, PNG for a document, ASCII and Unicode for a terminal, and JSON for the raw layout coordinates. The text forms are the ones agents actually use: an agent reading a pull request or a CI log sees the diagram as box-drawing characters it can parse, where an image tag would be a dead link. The editor renders all three from the one source in the box on the left, so the Diagram, Unicode, and ASCII tabs are the same diagram under three encodings.
am render flow.mmd --format svg > flow.svg
am render flow.mmd --format png > flow.png
am render flow.mmd --format ascii # box-drawing, into the terminalThe loop
These are one loop. An agent parses the source, narrows it with asFlowchart, mutates a node, verifies the result, and serializes it back, then renders the same bytes every time and reads the ASCII when it cannot open an image. It runs the whole loop with no browser and without asking a person whether the picture looks right. That last part is what beautiful-mermaid had no reason to do, and the reason this fork exists.
The loop itself, drawn by Agentic Mermaid at build time from six lines of Mermaid.
Where it comes from
Mermaid is the text syntax these diagrams are written in; its own renderer draws them in a browser. Drawing that text without a browser has been tried before — mermaid-ascii renders Mermaid graphs as ASCII straight in a terminal. Beautiful Mermaid, from the team at Craft, is a zero-dependency TypeScript renderer that outputs both SVG and ASCII, with its ASCII engine ported from mermaid-ascii's Go. Agentic Mermaid forks Beautiful Mermaid and adds the typed editing and deterministic verification above it, so an agent can change a diagram and check it, where the renderers before it could only draw one.