Mermaid Code: A Local-First Diagram Editor Built for the AI Coding Era

yk — Wed, 15 Jul 2026 15:54:30 +0000

If you've used AI coding agents like Claude Code or Codex to generate architecture diagrams, you've probably hit the same friction: the agent writes Mermaid code, but to see it rendered you have to copy it into a browser, open mermaid.live, paste, wait. Change one line, repeat the whole cycle.

I built Mermaid Code to eliminate that loop entirely.

The Problem with Browser-Based Editors

Mermaid Live Editor is great for one-off diagrams. But when diagrams become part of your codebase — living next to the code they describe — the browser workflow breaks down:

Every edit requires a new URL or a manual paste
Files don't persist; you lose work on tab close
AI agents can't access your browser tab
There's no way to manage a folder of diagrams

Cloud solutions like Mermaid Chart solve some of this, but unlimited storage requires a paid subscription.

Enter Mermaid Code

Mermaid Code is a free, open-source desktop app (macOS and Windows) that treats .mmd files as first-class citizens. Diagrams live on your filesystem, alongside your code, like any other source file.

Open a folder, and you get a full file manager sidebar. Create, rename, delete .mmd files without leaving the editor. Switch between diagrams with tabs. Come back tomorrow and your tabs are exactly where you left them.

The AI Workflow That Actually Works

Here's what the workflow looks like with an AI agent:

You: "Generate a sequence diagram for the OAuth flow and save it to docs/auth.mmd"

Agent: [writes docs/auth.mmd]

Mermaid Code: [detects the change, renders preview instantly]

No copy-pasting. No browser. No URL sharing. The file watcher picks up changes the moment the agent writes them, and the preview refreshes automatically.

This closes a loop that browser-based editors structurally can't close — because they have no access to your local filesystem. And since everything stays local, sensitive diagrams — architecture diagrams, database schemas, internal system topologies — never leave your machine. No terms of service, no data retention policies to worry about.

Thumbnail Grid: Navigate Diagrams Visually

When you have dozens of diagrams in a project, the file tree gets unwieldy. Mermaid Code has a thumbnail grid view that shows SVG previews of every diagram in your folder and its subdirectories.

Click a thumbnail to open it. Search by filename. The grid works across nested subdirectories, so even a sprawling docs/ folder is navigable at a glance.

Features Worth Mentioning

Vim mode — if you live in Vim, the editor has full Vim keybindings including :w to save and :q to close a tab.

Config form — set theme, layout engine (dagre/elk/tidy-tree), and look without touching JSON. A "Pin to code" button inserts the config as YAML frontmatter directly into the diagram file.

Presentation mode — press the expand button to go fullscreen with the sidebar still visible. Switch between diagrams during a presentation without exiting fullscreen.

Auto-update — the app checks for new versions on launch and downloads in the background.

Installation

macOS (Homebrew):

brew tap m8524769/tap
brew install --cask mermaid-code

macOS / Windows (direct download):
github.com/m8524769/mermaid-code/releases

macOS note: the app is not signed with an Apple Developer certificate. On first launch, go to System Settings → Privacy & Security and click Open Anyway.

It's Free and Open Source

Mermaid Code is MIT-licensed and built on top of the excellent mermaid-live-editor. The desktop layer is Tauri, which keeps the binary small and the memory footprint low compared to Electron alternatives.

If this solves a pain point for you, a GitHub star helps others find it.

→ github.com/m8524769/mermaid-code

DEV Community: yk