README
¶
mmdp
Lightweight CLI for AI agents and developers to preview Mermaid diagrams in a native frameless window (macOS).
Designed for AI coding agents (Claude Code, etc.) to visualize diagrams mid-conversation via stdin, and for developers to live-preview diagram files.
Why
- One pipe, one window.
echo "graph LR; A-->B" | mmdp— done. - Fire-and-forget. CLI exits immediately, window stays open. No cleanup needed.
- No dependencies. Single binary with embedded mermaid.js — no browser, no Node.js.
- Live reload. Point at a file, edit it, see changes instantly.
Install
Homebrew (macOS)
brew tap mxcoppell/tap
brew install mmdp
Or as a one-liner:
brew install mxcoppell/tap/mmdp
To upgrade to the latest version:
brew update && brew upgrade mmdp
Download binary
Grab the latest release from GitHub Releases.
Build from source
go build -ldflags="-s -w" -o bin/mmdp .
Quick Start
# Pipe from stdin (CLI exits immediately, window stays open)
echo "graph LR; A-->B-->C" | mmdp
# Preview a file (live reload on changes)
mmdp diagram.mmd
# Multiple files — each gets its own window
mmdp flow.mmd sequence.mmd
# Extracts ```mermaid blocks from markdown
mmdp README.md
Use Cases
| Scenario | How |
|---|---|
| Agent visualizes architecture mid-chat | Agent pipes Mermaid to stdin → window appears, agent continues |
| "Show me the data flow" | Agent generates diagram, runs in subagent — no context wasted |
| Debug a state machine | Agent renders current vs expected states in side-by-side windows |
| Review PR diagrams | mmdp docs/*.mmd — each file gets its own window |
| Live-edit a diagram | mmdp flow.mmd — instant reload on save |
| Preview docs | Extracts ```mermaid blocks from markdown automatically |
Supported Files
| Extension | Behavior |
|---|---|
.mmd, .mermaid |
Mermaid diagram files |
.md, .markdown |
Extracts ```mermaid fenced blocks |
CLI Flags
| Flag | Default | Description |
|---|---|---|
-p, --port PORT |
auto | Server port |
-t, --theme THEME |
system | dark, light, or system |
-w, --no-watch |
false | Disable file watching |
--poll INTERVAL |
— | Stat-based polling fallback (e.g. 500ms) |
-v, --version |
— | Print version |
-h, --help |
— | Print help |
Keyboard Shortcuts
| Key | Action |
|---|---|
Cmd+F |
Search nodes |
T |
Toggle theme (system → light → dark) |
+ / - |
Zoom in / out |
0 |
Reset zoom (fit to viewport) |
Esc |
Close search, or close window |
Space |
Close window |
Stdin
Pipe any mermaid source to stdin. The CLI renders it and exits immediately — the window stays open independently. Max input: 10MB.
Exit Codes
| Code | Meaning |
|---|---|
0 |
Success |
1 |
Argument error (bad flags, missing file) |
2 |
Runtime error (port in use, read failure) |
Agent Integration
mmdp includes a Claude Code skill that lets agents automatically discover and use it when you ask to visualize diagrams.
Install the skill
# Clone the repo (or use an existing checkout)
git clone https://github.com/mxcoppell/mmdp.git
# Symlink the skill (stays up to date with git pull)
mkdir -p ~/.claude/skills/mmdp
ln -s "$(pwd)/mmdp/skills/mmdp.md" ~/.claude/skills/mmdp/SKILL.md
Once installed, asking Claude Code to "show this as a diagram" or "visualize this flow" will automatically pipe Mermaid source through mmdp.
For best results, agents should run mmdp in a subagent — diagram rendering is a visual side-effect with no output to return, so delegating it keeps the main conversation context clean.
Contributing
# Build
go build -ldflags="-s -w" -o bin/mmdp .
# Run tests
go test ./...
# E2E tests (requires Node.js)
cd e2e && npm ci && npx playwright install chromium && npx playwright test
License
MIT
Directories