Nereid - Mermaid charts

Crea y explora diagramas Mermaid en colaboración con agentes de IA

Documentación

nereid

Nereid es un espacio de trabajo orientado a terminal para diagramas basados en Mermaid. Combina un TUI ratatui, un servidor Model Context Protocol (MCP), persistencia de sesiones basada en carpetas y representaciones de texto deterministas para que humanos y agentes de IA puedan inspeccionar y actualizar la misma sesión de diagramas.

Usa Nereid cuando quieras:

navegar y editar diagramas de secuencia, flujo, clase, entidad-relación (ER) y Gantt desde una terminal,
mantener diagramas, recorridos, referencias cruzadas, selecciones y estado activo en una carpeta de sesión local,
exponer herramientas MCP tipadas para navegación de diagramas, mutación estructurada (incluyendo bloques de secuencia), xrefs, recorridos y consultas de grafos,
reemplazar fuentes Mermaid con reconciliación que preserva identidad cuando las huellas digitales aún coinciden,
exportar fuentes Mermaid más vistas previas de texto para flujos de trabajo revisables basados en archivos.

Nereid está disponible con código fuente solo para uso no comercial. El uso comercial, uso de producto, uso de servicio de pago, uso comercial interno, redistribución, sublicencia o distribución modificada requiere permiso escrito por separado. Ver Licencia.

Lanzamientos recientes

0.9: Se agregaron diagramas de clase, entidad-relación y Gantt en el análisis, renderizado de texto, TUI, sesiones persistentes y lecturas MCP tipadas. La demo integrada ahora cubre las cinco familias de diagramas.
0.8: Se agregaron operaciones estructuradas de bloques y secciones de secuencia, además de diagram_replace_from_mermaid, que reconcilia identidades estables durante reescrituras masivas de Mermaid e informa xrefs colgantes.
0.7: Se agregó el conmutador de diagramas difuso : y anclas de símbolos Frigg persistentes para participantes de secuencia y nodos de diagrama de flujo.

Ver CHANGELOG.md para el historial completo de lanzamientos.

Instalación

Requisitos previos

Rust 1.85 o más reciente al instalar con Cargo o compilar desde el código fuente.
Una terminal que admita aplicaciones TUI de pantalla alternativa.
Opcional: VISUAL o EDITOR para el editor Mermaid integrado. Nereid recurre a vi.

Instalar Nereid no otorga derechos ilimitados. La misma licencia no comercial de código fuente disponible se aplica a crates.io, Homebrew, GitHub Releases, npm, Docker y compilaciones desde el código fuente.

Cargo

cargo install nereid
nereid --version

Homebrew

brew install bnomei/nereid/nereid
nereid --version

envoltorio npm

Requiere Node.js 18 o más reciente. El envoltorio admite Linux y macOS en x64 o arm64, además de Windows en x64. Linux y macOS también necesitan tar para extraer el archivo de lanzamiento descargado.

npx @bnomei/nereid --version

El paquete npm es un envoltorio delgado. En la primera ejecución descarga el binario correspondiente de GitHub Release, verifica el .sha256 publicado, lo almacena en caché localmente y reenvía argv al binario.

Docker

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

La imagen se construye a partir de los activos de lanzamiento de Linux musl publicados. Prefiere vincular un directorio de sesión para trabajo MCP o respaldado por archivos:

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

La bandera -i mantiene stdin abierto para el transporte MCP stdio. Agrega también -t cuando ejecutes el TUI interactivo en Docker.

Lanzamientos de GitHub

Descarga un archivo de lanzamiento desde Lanzamientos de GitHub, revisa el aviso de licencia incluido, extrae el archivo y coloca el binario nereid en tu PATH.

Desde el código fuente

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

Inicio rápido

Ejecuta la sesión de demostración integrada:

nereid --demo

Desde un clon del código fuente, usa Cargo:

cargo run -- --demo

Resultado esperado:

El TUI se abre con diagramas de demostración.
Presiona ? para abrir la ayuda integrada.
Presiona q para salir.
Mientras el TUI se ejecuta, MCP está disponible sobre HTTP Streamable en http://127.0.0.1:27435/mcp.

Crea o abre una carpeta de sesión persistente:

mkdir my-session
nereid my-session

Si la carpeta no tiene metadatos de sesión, ni archivos diagrams/*.mmd existentes, ni archivos walkthroughs/*.wt.json existentes, Nereid inicializa un diagrama semilla flow. Si existen archivos de diagrama o recorridos duraderos sin nereid-session.meta.json, Nereid se niega a sembrar una nueva sesión para que esos archivos no queden huérfanos; restaura el índice de metadatos para reparar la sesión. Para una sesión existente, Nereid carga el índice de metadatos y sus archivos de diagrama y recorridos referenciados.

Modos de ejecución

Tarea	Comando	Resultado
Abrir el directorio actual como sesión TUI	`nereid`	Carga o inicializa `.` e inicia MCP HTTP en el puerto `27435`.
Abrir una carpeta de sesión específica	`nereid path/to/session`	Carga o inicializa esa carpeta.
Usar una bandera de sesión explícita	`nereid --session path/to/session`	Igual que un directorio de sesión posicional.
Ejecutar la sesión de demostración	`nereid --demo`	Inicia el TUI con una sesión de demostración temporal.
Cambiar el puerto HTTP MCP del TUI	`nereid --mcp-http-port 27500`	Sirve MCP en `http://127.0.0.1:27500/mcp`.
Ejecutar MCP sobre stdio sin el TUI	`nereid --mcp --session path/to/session`	Sirve MCP en stdin/stdout para integraciones de herramientas.
Imprimir la instantánea del esquema MCP	`nereid --dump-mcp-tool-schema`	Imprime los esquemas de herramientas registrados y sale.
Mostrar ayuda de CLI	`nereid --help` o `nereid -h`	Imprime las formas y opciones de comando admitidas.
Mostrar la versión instalada	`nereid --version` o `nereid -V`	Imprime el nombre del paquete y la versión.

Sinopsis de CLI:

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

Reglas:

Si se omiten session-dir y --session, Nereid usa el directorio de trabajo actual.
--demo no se puede combinar con un directorio de sesión.
--mcp-http-port solo es válido en modo TUI.
--durable-writes opta por una persistencia duradera más lenta de mejor esfuerzo con fsync o sync donde se admita.

Fuente: src/main.rs.

Carpetas de sesión

Una carpeta de sesión es la fuente de verdad para el estado duradero de Nereid. Tanto el TUI como el servidor MCP persistente leen y escriben en esta carpeta.

Ruta	Propósito
`nereid-session.meta.json`	Id de sesión, ids de diagrama y recorrido activos, índice de diagramas, xrefs y estado de selección.
`diagrams/*.mmd`	Fuente Mermaid canónica para cada diagrama.
`diagrams/*.meta.json`	Mapas de id estables y metadatos extraídos para diagramas persistidos.
`diagrams/*.ascii.txt`	Exportación de renderizado de texto de mejor esfuerzo para cada diagrama. La extensión es heredada; el contenido puede incluir dibujo de cajas Unicode.
`walkthroughs/*.wt.json`	Datos de grafo de recorridos.
`walkthroughs/*.ascii.txt`	Exportación de renderizado de texto de mejor esfuerzo para cada recorrido.
`.nereid-session.write.lock`	Bloqueo de escritura transitorio usado durante los guardados de sesión.

Nereid puede reescribir archivos administrados mientras se ejecuta. Usa la tecla e del TUI para editar el diagrama activo en $VISUAL o $EDITOR, o detén Nereid antes de hacer cambios manuales. Las exportaciones de renderizado de texto se generan de forma asíncrona y pueden quedarse brevemente atrás de las actualizaciones de .mmd o .wt.json durante ediciones rápidas.

Fuente: src/store/session_folder.rs.

Soporte de Mermaid

Nereid analiza un subconjunto deliberado de Mermaid e informa la sintaxis no admitida como un error accionable.

Los diagramas de secuencia admiten:

sequenceDiagram como primera línea no vacía,
comentarios que comienzan con %%,
declaraciones participant <name> y <role> <name>,
líneas de mensaje como alice->>bob: Hello,
flechas de mensaje de Mermaid normalizadas internamente a mensajes sync, async o return,
bloques alt, opt, loop y par,
else dentro de alt, and dentro de par y cierres de bloque end.

Los diagramas de flujo admiten:

flowchart o graph como primera línea no vacía, con dirección opcional TD, TB, LR, RL o BT,
comentarios que comienzan con %%,
declaraciones de nodo: <id>, <id>[<label>], <id>(<label>) y <id>{<label>},
aristas con operadores comunes de diagramas de flujo de Mermaid, normalizadas internamente,
etiquetas de arista en formas A -->|label| B y A -- label --> B,
aristas encadenadas como A --> B --> C,
sentencias linkStyle, que se conservan en la exportación. Los estilos por arista que contienen la palabra literal dashed producen trazos discontinuos en el renderizado de texto; otras propiedades CSS y linkStyle default no afectan el renderizado de texto.

Los diagramas de clase admiten:

classDiagram como primera línea no vacía,
comentarios que comienzan con %%,
nombres de clase simples que contienen letras ASCII, dígitos, guiones bajos o guiones,
miembros en forma ClassName : member; los miembros que contienen ( son métodos y el resto son atributos,
relaciones de herencia, composición, agregación, asociación, dependencia, realización y enlace simple,
etiquetas de relación opcionales después de :,
notas de clase almacenadas en el sidecar del diagrama.

Los diagramas de entidad-relación admiten:

erDiagram como primera línea no vacía,
comentarios que comienzan con %%,
nombres de entidad simples que contienen letras ASCII, dígitos, guiones bajos o guiones,
relaciones identificadoras (--) y no identificadoras (..),
tokens de cardinalidad de Mermaid ||, |o, o|, |{, }|, }o y o{,
etiquetas de relación opcionales después de :,
notas de entidad almacenadas en el sidecar del diagrama.

Los diagramas de Gantt admiten:

gantt como primera línea no vacía,
comentarios que comienzan con %%,
líneas opcionales title y dateFormat,
grupos nombrados section,
tareas con una etiqueta opcional, un inicio absoluto YYYY-MM-DD o una dependencia after <tag>, y una duración en días como 14d,
notas de tarea y de carril de tiempo renderizado almacenadas en el sidecar del diagrama.

Los nombres de participantes de secuencia y nodos de diagrama de flujo analizados deben ser cadenas alfanuméricas ASCII no vacías o guiones bajos. No pueden contener espacios en blanco ni /. Los nombres de clase y ER también permiten guiones. Las etiquetas de tareas de Gantt son texto libre antes de los dos puntos de metadatos de la tarea.

Fuentes: src/format/mermaid/sequence.rs, src/format/mermaid/flowchart.rs, src/format/mermaid/class.rs, src/format/mermaid/er.rs, src/format/mermaid/gantt.rs, src/format/mermaid/ident.rs.

TUI

Presiona ? en Nereid para el panel de ayuda completo desplazable.

Teclas comunes:

Tecla	Acción
`q`	Salir.
`1`	Enfocar el panel de diagrama.
`2` / `3`	Alternar y enfocar Objetos / XRefs.
`4` / `5`	Alternar Inspector / Notas.
`Tab` / `Shift-Tab`	Enfocar panel siguiente / anterior.
`[` / `]`	Abrir diagrama anterior / siguiente.
`:`	Abrir el conmutador de diagramas difuso; `Tab` completa el resultado seleccionado `[SEQ]`, `[FLO]`, `[CLS]`, `[ER]` o `[GNT]`.
`/` / `\`	Búsqueda regular / difusa.
`n` / `N`	Siguiente / anterior resultado de búsqueda.
Flechas o `h`/`j`/`k`/`l`	Desplazarse o moverse dentro del panel enfocado.
`f`	Modo de salto por pistas.
`c`	Modo de selección de pistas en cadena.
`Space`	Alternar objeto seleccionado.
`d`	Deseleccionar todos los objetos en el diagrama actual.
`y`	Copiar la referencia del objeto seleccionado con OSC52.
`g` / `t`	Saltar a través de xrefs entrantes / salientes.
`e`	Editar el diagrama activo en `$VISUAL`, `$EDITOR` o `vi`.
`a`	Alternar atención de seguimiento de IA.

Anulación de paleta

Por defecto, Nereid utiliza la paleta ANSI del terminal. Establece NEREID_TUI_PALETTE para anular el primer plano, el fondo y los 16 colores ANSI.

Forma del valor:

<fg>,<bg>,<black>,<red>,<green>,<yellow>,<blue>,<magenta>,<cyan>,<white>,<bright_black>,<bright_red>,<bright_green>,<bright_yellow>,<bright_blue>,<bright_magenta>,<bright_cyan>,<bright_white>

Cada color debe ser #RRGGBB, 0xRRGGBB o rgb:rr/gg/bb. NEREID_PALETTE se acepta como alias.

Fuentes: src/tui/chrome.rs, src/tui/theme.rs.

MCP

Nereid expone herramientas MCP para la colaboración en vivo de diagramas.

El servidor anuncia solo herramientas; no expone recursos ni indicaciones de MCP. Los playbooks del repositorio descritos a continuación son ejemplos para clientes MCP, no capacidades de indicaciones registradas.

Transportes:

Modo TUI: HTTP Streamable en http://127.0.0.1:<port>/mcp, puerto predeterminado 27435.
Modo Stdio: nereid --mcp --session path/to/session.

Conectar un cliente MCP

Para clientes que inician servidores stdio, agrega una entrada de servidor como esta y reemplaza la ruta de sesión con una ruta absoluta:

{
  "mcpServers": {
    "nereid": {
      "command": "nereid",
      "args": ["--mcp", "--session", "/absolute/path/to/session"]
    }
  }
}

Si Nereid ya se está ejecutando en modo TUI, conecta un cliente HTTP Streamable a http://127.0.0.1:27435/mcp, o al puerto seleccionado con --mcp-http-port.

Grupos de herramientas:

Ciclo de vida y lecturas de diagramas: diagram_list, diagram_current, diagram_open, diagram_delete, diagram_read, diagram_stat, diagram_get_ast, diagram_get_slice, diagram_render_text, diagram_diff.
Creación y mutación de diagramas: diagram_create_from_mermaid, diagram_replace_from_mermaid, diagram_propose_ops, diagram_apply_ops (operaciones de estructura de secuencia para bloques/secciones/membresía).
Recorridos: walkthrough_list, walkthrough_current, walkthrough_open, walkthrough_read, walkthrough_stat, walkthrough_get_node, walkthrough_render_text, walkthrough_diff, walkthrough_apply_ops.
Estado de colaboración: attention_human_read, attention_agent_read, attention_agent_set, attention_agent_clear, follow_ai_read, follow_ai_set, selection_read, selection_update, view_read_state.
Referencias cruzadas y objetos: xref_list, xref_neighbors, xref_add, xref_remove, object_read.
Consultas: route_find, seq_messages, seq_search, seq_trace, flow_reachable, flow_paths, flow_cycles, flow_unreachable, flow_dead_ends, flow_degrees.

Las referencias de objetos usan esta forma canónica:

d:<diagram_id>/<category...>/<object_id>

Ejemplos:

d:demo-flow/flow/node/n:a
d:demo-seq/seq/message/m:0001
d:demo-seq/seq/block/b:0000
d:demo-seq/seq/section/sec:0000:00
d:demo-class/class/class/c:Class01
d:demo-class/class/relation/r:0001
d:demo-er/er/entity/e:CUSTOMER
d:demo-er/er/relationship/r:0001
d:demo-gantt/gantt/section/sec:0001
d:demo-gantt/gantt/task/t:0001
d:demo-gantt/gantt/lane/lane:2014-01-01

Los pares de categorías canónicas son seq/participant, seq/message, seq/block, seq/section, flow/node, flow/edge, class/class, class/relation, er/entity, er/relationship, gantt/section, gantt/task y gantt/lane.

Los carriles de Gantt con inicios de tareas YYYY-MM-DD válidos usan ids estables de calendario como lane:2026-01-08; los gráficos sin fechas absolutas analizables usan ids relativos como lane:0007.

Anclas de símbolos de código

Los participantes de secuencia y los nodos de diagramas de flujo pueden llevar un ancla opcional de símbolo de código Frigg con un stable_symbol_id hexadecimal en minúsculas como sym-16c57df0026ced40 y un repository_id opcional. Establece o limpia anclas con las operaciones seq_set_participant_symbol y flow_set_node_symbol pasadas a diagram_apply_ops o diagram_propose_ops.

Las anclas aparecen en las respuestas de diagram_get_ast y object_read. Nereid las persiste en diagrams/*.meta.json, separadas del código fuente de Mermaid, por lo que agregar un ancla no reescribe el archivo .mmd correspondiente.

Los diagramas de secuencia y de flujo admiten operaciones de mutación MCP estructuradas. Edita diagramas de clase, ER y Gantt con diagram_replace_from_mermaid o el editor TUI; sus lecturas de AST y objetos específicos del tipo permanecen disponibles para inspección y verificación.

Prefiere operaciones de estructura para ediciones locales de alt/opt/loop/par. Usa diagram_replace_from_mermaid para reescrituras masivas de Mermaid; las huellas digitales coincidentes mantienen ids estables, y la respuesta informa ids preservados/eliminados/nuevos más referencias cruzadas colgantes en el diagrama de destino.

La instantánea de esquema revisable se encuentra en src/mcp/server/tool_schema.snapshot.json. Regenera después de cambiar nombres de herramientas, descripciones, esquemas de entrada o esquemas de salida:

cargo run -- --dump-mcp-tool-schema > src/mcp/server/tool_schema.snapshot.json
cargo test mcp_tool_schema_snapshot_is_current

Fuentes: src/mcp/server.rs, src/mcp/server/tool_schema.snapshot.json, src/model/object_ref.rs.

Datos de demostración y playbooks

El repositorio incluye una sesión de demostración persistida en data/demo-session. Contiene diagramas de secuencia, flujo, clase, ER y Gantt, además de referencias cruzadas y un recorrido que ejercitan las herramientas TUI y MCP. El índice de demostración enlaza a cada familia de diagramas.

Los indicaciones de playbook para clientes MCP se encuentran en tests/playbooks. Las tareas de ejemplo incluyen:

"Desde el índice de demostración, lista cada referencia cruzada de navegación que aterrice en un diagrama de secuencia."
"Crea un diagrama de flujo temporal, elimínalo y confirma que desapareció de diagram_list."
"Construye un bloque alt/else con operaciones de estructura, o reemplaza Mermaid mientras preservas los ids de mensaje."
"Inspecciona la relación places en la demostración de ER y devuelve su referencia de relación canónica."
"Sigue la dependencia after de Gantt desde Another task de vuelta a A task."

Desarrollo

Ejecuta las verificaciones estándar antes de la revisión:

cargo fmt
cargo clippy --all-targets --all-features
cargo test

Ejecuta las líneas base de referencia de Criterion:

./scripts/bench-criterion save
./scripts/bench-criterion compare

Ejecuta los hooks locales de pre-commit:

prek validate-config prek.toml
prek run --all-files
prek install

Los ayudantes de lanzamiento se encuentran en scripts, y los flujos de trabajo de GitHub Actions en .github/workflows.

Licencia

Licencia no comercial de código fuente disponible de Nereid v1.0. El uso no comercial solo está permitido bajo los términos en LICENSE. El uso comercial, uso de producto, uso de servicio de pago, uso comercial interno, redistribución, sublicenciamiento, distribución modificada o incorporación en otro proyecto requiere permiso previo por escrito del titular de los derechos de autor.