---
title: Mermaid diagrams (draw a diagram inside a chat message)
---

# Mermaid diagrams (render diagrams in chat)

## What it is

### What it is

[Mermaid](https://mermaid.js.org/) is a plain-text way to describe diagrams —
flowcharts, sequence diagrams, class diagrams, state machines, and more — by
writing a few lines of text inside a fenced code block:

````
```mermaid
graph TD
  A[Start] --> B{Works?}
  B -->|Yes| C[Ship it]
  B -->|No| D[Fix it]
```
````

When an AI agent (or anyone) writes a block like that in a chat message, Omniscio now
**draws it as an actual diagram** right in the conversation, instead of showing
the raw text. The picture matches your light/dark theme, and wide diagrams scroll
sideways so they fit on a phone.

## Where to find it

In the chat. There is nothing to open and no setting to find — any message containing a ```mermaid block draws its diagram in place.

## How it behaves

### How to use it

You don't need to do anything — it's automatic and always on. Whenever a chat
message contains a ```mermaid block, the diagram is drawn in place.

- **See the underlying text.** Hover the diagram and click the **`</>` (view
  source)** button in its top-right corner to flip between the picture and the
  raw Mermaid text; the **copy** button next to it copies the source.
- **While a reply is still streaming**, Omniscio shows the source text and draws the
  diagram the moment the message finishes — so you never see a half-drawn,
  flickering picture.
- **If a diagram can't be drawn** (the syntax has a typo, or it's enormous), Omniscio
  quietly falls back to showing the source text rather than an error — nothing is
  ever lost.

The same rendering also powers two other places in Omniscio:

- **File preview** — opening a `.mmd` / `.mermaid` file (or a Markdown file that
  contains a ```mermaid block) shows the drawn diagram.
- **Mind Map → "View as Mermaid"** — the read-only preview of a mind map as a
  Mermaid diagram.

### Is it safe?

Yes. Chat content can come from an AI, so Omniscio treats every diagram as untrusted:
it renders Mermaid in **strict mode** (no embedded HTML or click handlers) and
runs the resulting image through the same SVG sanitizer used everywhere else
before it's shown. A malicious diagram can't run code.

### Settings

There is no setting — native rendering is always on, with the per-diagram
view-source toggle if you'd rather read the text.

## For agents

### Implementation pointers (for agents touching this code)

- Shared engine: [src/renderer/src/components/ui/MermaidDiagram.tsx](/src/renderer/src/components/ui/MermaidDiagram.tsx) — dynamic `import('mermaid')`, `securityLevel: 'strict'`, `sanitizeSvgMarkup`, theme-keyed init, graceful `fallback`. The ONLY place that calls `mermaid.render`.
- Chat wiring: [src/renderer/src/components/ui/AgentMarkdown.tsx](/src/renderer/src/components/ui/AgentMarkdown.tsx) — the `markdownComponents.pre` override detects a `language-mermaid` block → `ChatMermaidBlock` (diagram + view-source toggle + copy); `MermaidStreamingContext` defers the draw while streaming.
- Other consumers: [PreviewRenderer.tsx](/src/renderer/src/features/file-explorer/PreviewRenderer.tsx) (`MermaidPreview`) and [MermaidDialog.tsx](/src/renderer/src/features/mindmap/MermaidDialog.tsx) (`View as Mermaid`).
- Rulebook + invariants: [.claude/memory/contracts/mermaid-rendering.md](/.claude/memory/contracts/mermaid-rendering.md). Sanitizer: [.claude/memory/contracts/preview-sanitizer-contract.md](/.claude/memory/contracts/preview-sanitizer-contract.md).
- Tests: [tests/unit/components/MermaidDiagram.test.tsx](/tests/unit/components/MermaidDiagram.test.tsx), [tests/unit/components/agent-markdown-mermaid.test.tsx](/tests/unit/components/agent-markdown-mermaid.test.tsx).

## Related

### Related

- [agent-message-display.md](agent-message-display.md) — how the rest of an agent's message (prose, tool activity) renders around the diagram.
- [mindmap.md](mindmap.md) — the Mind Map feature and its "View as Mermaid" panel.
- [copy-session-as-markdown.md](copy-session-as-markdown.md) — exporting a conversation (the diagram's source travels as the original ```mermaid block).