Neptunus

Preview Mermaid diagrams natively on macOS. Your AI agent pushes them to a real window for you to review.

Download

v0.1.0 · macOS 15+ · Apple Silicon

Your agent calls preview_mermaid, Neptunus opens the diagram in a real window, and your Approve or Deny goes back to the agent.

See what your AI agent is proposing

Working with AI agents, you collect a lot of Mermaid diagrams: schemas, flows, sequences. As they grow, the raw source gets hard to read and it is easy to lose the overview. Neptunus renders them the way you would actually see them, so you can check your agent's diagram at a glance and approve or reject it without leaving your editor.

Credit-ledger.mmd A Mermaid flowchart of a credit ledger, rendered by Neptunus
Ledger ER.mmd A Mermaid ER diagram of the same ledger, rendered by Neptunus

Real Mermaid, fully offline

Diagrams render with the bundled mermaid.js in a native WKWebView. No CDN, no internet needed. Flowcharts, sequence, ER, state and the rest, in light or dark to match your Mac.

Your agent pushes, you review

A local MCP server exposes a preview_mermaid tool. Your AI agent sends a diagram straight to the app; in review mode it waits for your Approve or Deny and gets the answer back.

Preview, or edit side by side

Open a .mmd file or paste source. Toggle between a clean preview and a split view with a live editor that re-renders as you type.

Zoom, pan, export

Fit to the window or zoom to 800%. Shift-scroll and Space-drag like a real canvas, then export any diagram to SVG, PNG or PDF.

Always one keystroke away

Neptunus lives in the menu bar and keeps running so agents can reach it any time. The Dock icon appears only when a window is open, and it updates itself in the background.

A real macOS app

Swift and SwiftUI, document-based, signed and notarized. Open and save .mmd and .mermaid files like any other document.

Add the MCP server

Install the app in /Applications and keep it running, then add the MCP server to your agent.

Claude Code (CLI)
claude mcp add -s user neptunus -- "/Applications/Neptunus.app/Contents/MacOS/neptunus-mcp"
Codex (CLI)
codex mcp add neptunus -- "/Applications/Neptunus.app/Contents/MacOS/neptunus-mcp"

The app's Settings → MCP tab has a Copy button with your exact path, plus a .mcp.json snippet for Cursor and Claude Desktop.

Changelog

Every release, newest first.

  1. 0.1.0

    Initial release

    • Document-based app for `.mmd` / `.mermaid` files plus pasted source, with a menu bar item that keeps it running after windows close.
    • Diagram rendering with vendored mermaid.js 11.15.0 in a `WKWebView`, fully offline, with a custom light/dark theme that follows your preference.
    • Preview/split toggle: look at the diagram, or edit the source alongside a live render (150 ms debounce).
    • Zoom and fit: fills the window by default, manual zoom to 800% via slider and 50/100/200/400/800% presets, Shift + scroll to zoom, and Space + drag to pan. Crisp vector SVG.
    • Local MCP server: agents connect via the bundled `neptunus-mcp` helper over a `0600` unix socket and call `preview_mermaid` to render a diagram here. `wait_for_review` blocks until you accept or reject and returns the verdict.
    • Settings → MCP: live server status, a Restart control, connected clients, the helper path, and copy-paste `claude mcp add` / `.mcp.json` snippets. The menu bar mirrors the status.
    • Export the diagram to SVG, PNG, or PDF.
    • Dock icon only while a window is open; otherwise menu-bar-only, still running.
    • Automatic updates via Sparkle.