Nereid - Mermaid charts

Create and explore Mermaid diagrams in collaboration with AI agents

Nereid is a terminal-first workspace for Mermaid-backed diagrams. It combines aratatuiTUI, a Model Context Protocol (MCP) server, folder-based session persistence, and deterministic text renders so humans and AI agents can inspect and update the same diagram session.

- browse and edit sequence, flowchart, class, entity-relationship (ER), and Gantt diagrams from a terminal,
- keep diagrams, walkthroughs, cross-references, selections, and active state in a local session folder,
- expose typed MCP tools for diagram navigation, structured mutation (including sequence blocks), xrefs, walkthroughs, and graph queries,
- replace Mermaid sources with identity-preserving reconcile when fingerprints still match,
- export Mermaid sources plus text previews for reviewable, file-based workflows.

Nereid is source-available for noncommercial use only. Commercial use, product use, paid service use, internal business use, redistribution, sublicensing, or modified distribution requires separate written permission. SeeLicense.

SeeCHANGELOG.mdfor the complete release history.

brew install bnomei/nereid/nereid nereid --version

docker run --rm ghcr.io/bnomei/nereid:0.9.0 --version

docker run --rm -i -v "$PWD/my-session:/workspace/my-session" ghcr.io/bnomei/nereid:0.9.0 --mcp --session /workspace/my-session

Download a release archive fromGitHub Releases, review the included license notice, extract the archive, and put thenereidbinary on yourPATH.

git clone https://github.com/bnomei/nereid.git cd nereid cargo build --release ./target/release/nereid --version

nereid [<session-dir>] [--durable-writes] [--mcp-http-port <port>] nereid [--session <dir>] [--durable-writes] [--mcp-http-port <port>] nereid --demo [--mcp-http-port <port>] nereid [<session-dir>] [--durable-writes] --mcp nereid [--session <dir>] [--durable-writes] --mcp nereid --demo --mcp nereid --dump-mcp-tool-schema

- Ifsession-dirand--sessionare omitted, Nereid uses the current working directory.
- --democannot be combined with a session directory.
- --mcp-http-portis only valid in TUI mode.
- --durable-writesopts into slower best-effort durable persistence with fsync or sync where supported.

A session folder is the source of truth for durable Nereid state. The TUI and persistent MCP server both read and write this folder.

Nereid may rewrite managed files while it runs. Use the TUIekey to edit the active diagram in$VISUALor$EDITOR, or stop Nereid before making manual changes. Text render exports are generated asynchronously and can briefly lag behind.mmdor.wt.jsonupdates during rapid edits.

Nereid parses a deliberate Mermaid subset and reports unsupported syntax as an actionable error.

- sequenceDiagramas the first non-empty line,
- comments beginning with%%,
- participant <name>and<role> <name>declarations,
- message lines such asalice->>bob: Hello,
- Mermaid message arrows normalized internally to sync, async, or return messages,
- alt,opt,loop, andparblocks,
- elseinsidealt,andinsidepar, andendblock closures.

- flowchartorgraphas the first non-empty line, with optionalTD,TB,LR,RL, orBTdirection,
- comments beginning with%%,
- node declarations:<id>,<id>[<label>],<id>(<label>), and<id>{<label>},
- edges with common Mermaid flowchart operators, normalized internally,
- edge labels inA -->|label| BandA -- label --> Bforms,
- chained edges such asA --> B --> C,
- linkStylestatements, which are preserved on export. Per-edge styles containing the literal worddashedproduce dashed text-render strokes; other CSS properties andlinkStyle defaultdo not affect text rendering.

- classDiagramas the first non-empty line,
- comments beginning with%%,
- bare class names containing ASCII letters, digits, underscores, or hyphens,
- members inClassName : memberform; members containing(are methods and the rest are attributes,
- inheritance, composition, aggregation, association, dependency, realization, and plain-link relations,
- optional relation labels after:,
- class notes stored in the diagram sidecar.

- erDiagramas the first non-empty line,
- comments beginning with%%,
- bare entity names containing ASCII letters, digits, underscores, or hyphens,
- identifying (--) and non-identifying (..) relationships,
- Mermaid cardinality tokens||,|o,o|,|{,}|,}o, ando{,
- optional relationship labels after:,
- entity notes stored in the diagram sidecar.

- ganttas the first non-empty line,
- comments beginning with%%,
- optionaltitleanddateFormatlines,
- namedsectiongroups,
- tasks with an optional tag, an absoluteYYYY-MM-DDstart orafter <tag>dependency, and a day duration such as14d,
- task and rendered time-lane notes stored in the diagram sidecar.

Parsed sequence participant and flowchart node names must be non-empty ASCII alphanumeric strings or underscores. They cannot contain whitespace or/. Class and ER names additionally allow hyphens. Gantt task labels are free-form text before the task metadata colon.

…