MermAId Editor

A local Mermaid diagram editor designed for AI-assisted workflows. It's a pretty nice live Mermaid editor. But it's also a tool to be used with AI coding agents in generating plans. An AI coding agent (Claude Code, Codex, etc.) generates or updates diagrams via MCP or CLI, and you see the results rendered live in your browser. You can also edit diagrams directly — it's a full editor with syntax highlighting, linting, and vim keybindings. Push changes back to the agent, iterate, rinse and repeat.

The editor runs as a small Go server on localhost with a split-pane UI: a CodeMirror text editor on the left and a live Mermaid preview on the right.

<p> <img src="images/editor-ui-light.png" alt="Split-pane editor in light mode with code on the left and rendered diagram on the right" width="49%" /> <img src="images/editor-ui-dark.png" alt="Split-pane editor in dark mode with code on the left and rendered diagram on the right" width="49%" /> </p>

AI agents interact with the editor via MCP or CLI to generate and update diagrams programmatically.

The native macOS app bundle is a self-contained executable that lives in the Dock and is freestanding (including the MCP server).

Features

• AI agent integration via MCP server or CLI tool — agents can get and set diagrams programmatically
• Live preview with debounced rendering as you type
• Vim keybindings (via codemirror-vim)
• Mermaid syntax highlighting and linting
• Pan and zoom on the diagram preview
• Export diagrams as SVG or high-resolution PNG
• Collapsible editor pane
• Single-instance enforcement — re-running the binary focuses the existing session
• Cross-platform: runs on macOS, Linux, and Windows
• Builds as a native macOS .app bundle with a menu-bar icon (tray app)

Installation

Requirements

• Go 1.25+
• Node.js / npm
• macOS only: Xcode Command Line Tools (for CGO — the native app window uses Cocoa/WebKit)

Build from source (macOS / Linux)

git clone https://github.com/kmatthias/mermaid-editor.git
cd mermaid-editor
make build

This installs JS dependencies, bundles the frontend, and compiles the Go binary. The resulting binary is ./mermaid-editor — static assets are embedded at compile time, so the single file is all you need.

On macOS, the build uses CGO to link against Cocoa and WebKit for the native app window. On Linux, no CGO or system libraries are required.

Build from source (Windows)

Windows requires Go and Node.js installed. If you have GNU Make (e.g. via Chocolatey, MSYS2, or Git Bash):

make build

Without Make, run the steps manually in PowerShell:

npm install
npx esbuild frontend/app.js --bundle --format=iife --minify --sourcemap --outfile=static/bundle.js
copy frontend\style.css static\style.css
go build -o mermaid-editor.exe .

Install to PATH

# macOS / Linux: copy the binary somewhere on your PATH
cp mermaid-editor /usr/local/bin/

# Or use go install on any platform (requires GOBIN on PATH)
go install .

On Windows, copy mermaid-editor.exe to a directory on your %PATH%, or use go install ..

Usage

# Run the editor (opens in your default browser)
./mermaid-editor

# Run in development mode with live JS rebuilds
make dev

The editor opens automatically in your default browser. If an instance is already running, it focuses the existing window instead of starting a new one.

Platform notes

	macOS	Linux	Windows
Browser	Opens via open	Opens via xdg-open	Opens via rundll32
Native window	Yes (Cocoa/WebKit app)	No — browser only	No — browser only
App bundle	make macapp	N/A	N/A
CGO required	Yes (for native window)	No	No

macOS App Bundle

make macapp

Creates MermAId Editor.app, a self-contained macOS application that lives in the menu bar. This target is macOS-only.

AI Agent Integration (Claude Code, etc.)

There are two ways to connect an AI agent to the editor. Pick whichever fits your workflow — both provide the same get/set diagram capabilities.

	MCP Server	CLI Tool
How it works	Editor runs as an MCP server over stdio; the agent talks to it natively	A Ruby script calls the editor's HTTP API
Agent discovers tools	Automatically (via MCP protocol)	Via instructions you add to CLAUDE.md
Requirements	Just the binary	Ruby, plus a running editor instance
Best for	Dedicated agent sessions	When you're already using the editor interactively

---

Option A: MCP Server

The editor can run as an MCP server. In this mode it starts the HTTP server for the browser UI and exposes get_diagram / set_diagram tools over stdio. The agent discovers the tools automatically — no CLAUDE.md instructions needed.

Setup

Add the server to your Claude Code MCP config (~/.claude/settings.json or project .mcp.json):

{
  "mcpServers": {
    "mermaid-editor": {
      "command": "/path/to/mermaid-editor",
      "args": ["--mcp"]
    }
  }
}

That's it. Claude Code will start the editor when it needs it, and the MCP tools will be available automatically.

Tools

Tool	Description
get_diagram	Returns the current diagram text and version
set_diagram	Replaces the entire diagram (appears live in the browser)

---

Option B: CLI Tool

The editor ships with bin/mermaid-cli, a Ruby script that talks to a running editor instance over its HTTP API. You start the editor yourself and tell the agent about the CLI via CLAUDE.md.

Setup

1. Start the editor normally:

   ./mermaid-editor
   

2. Add the CLI to your CLAUDE.md (project or global) so the agent knows how to use it:

   ## Mermaid Diagrams
   
   A mermaid editor is running locally. Use `bin/mermaid-cli` to interact with it:
   
   - `bin/mermaid-cli get` — print the current diagram to stdout
   - `bin/mermaid-cli set --text "graph TD; A-->B"` — set the diagram from a string
   - `bin/mermaid-cli set diagram.mmd` — set the diagram from a file
   - `bin/mermaid-cli status` — check if the editor is running
   - For multiline diagrams, avoid literal `\n` in plain quotes. Use ANSI-C quoting or a file/heredoc so real newlines are passed, e.g. `bin/mermaid-cli set --text $'sequenceDiagram\n  A->>B: Hi'` or `cat <<'EOF' > /tmp/diagram.mmd` then `bin/mermaid-cli set /tmp/diagram.mmd`
   

How it works

The CLI discovers the running editor automatically via its state files and talks to it over its localhost HTTP API. Changes made via set appear instantly in the browser preview.

Commands

Command	Description
mermaid-cli get	Print the current diagram text to stdout
mermaid-cli set <file>	Replace the diagram from a file (- for stdin)
mermaid-cli set --text "…"	Replace the diagram from a string
mermaid-cli status	Check if the editor is running
mermaid-cli help	Show usage information

Other Make Targets

Target	Description
make help	Show all available targets
make test	Run the test suite
make stop	Stop a running instance
make clean	Remove build artifacts

Copyright 2026 Quantum Hug, Inc.