claude-mermaid

claude-mermaid draws the diagrams Claude writes. When a reply contains a mermaid code block, the transcript shows box art in its place, in color, exactly where the fence was. The hook draws locally, so it costs zero tokens. Nothing else appears on screen, no pane and no band above the prompt, and there is nothing to run.

The README’s example, a four-node flowchart, comes out like this:

  ┌────────┐     ┌────────────┐     ◇────────────◇     ┌───────┐
  │        │     │            │     │            │     │       │
  │ Prompt ├────►│ Understand ├────►│ Use Tools? ├─Yes►│ Reply │
  │        │     │            │     │            │     │       │
  └────────┘     └────────────┘     ◇────────────◇     └───────┘

What it does

• Draws six kinds: flowcharts, sequence, class, state and ER diagrams, and xy charts. Any other kind (gantt, pie, mindmap, gitGraph, journey, timeline, quadrant, C4 and the rest) keeps its fence as Claude wrote it.
• Lays a top-down flowchart or state diagram out left to right when that fits the width and every label survives, because rows are scarcer than columns in a terminal. /mermaid lr off keeps Claude’s direction.
• Colors from the terminal’s own 16-color palette, so light and dark themes both read: borders cyan, arrows yellow, plain lines dim. /mermaid color off for monochrome.
• /mermaid ascii on swaps the box-drawing glyphs for +, - and |, for a font that lacks them.
• /mermaid shows the current settings and /mermaid reset restores the defaults. A change redraws the diagrams already on screen, and the settings survive restarts.

Install

Needs Claude Code 2.1.270 or later with function hooks enabled, an interactive terminal and a font with box-drawing characters (or /mermaid ascii on).

claude plugin marketplace add galElmalah/claude-mermaid
claude plugin install claude-mermaid@claude-mods

claude-mods is the name of the author’s marketplace, which also carries a second plugin, claude-queue. It is not related to this site. Start claude and ask for a diagram: the art appears once the closing fence has streamed in.

How it works

The module hooks ui.render for the AssistantMessage component. Each time Claude Code is about to draw a reply, the hook scans the message text for closed mermaid fences, renders each one and passes the message on with the fence swapped for a text code block holding the art. The transcript draws that block like any other, and ANSI escapes inside it carry the colors. This is what sets the mod apart from the ones that draw in the band above the prompt: it rewrites the reply itself, so the diagram sits inside the conversation and scrolls with it. A block that fails to render keeps its fence.

The renderer is a bundled copy of beautiful-mermaid’s ASCII renderer, because hooks modules cannot import packages. Its edge router is capped, so a dense graph that ran for 25 seconds upstream draws in about 60 ms. Art is cached per source and glyph set, so a redraw takes a few milliseconds.

The hook reads only the text of Claude’s replies. It makes no network calls, asks the model nothing and stores one thing on your machine: the three /mermaid settings, in the plugin’s store. session.start loads them and registers the command; command.run answers /mermaid.

Limitations

• Nothing draws in claude -p.
• Color is terminal only. The desktop app and mobile strip ANSI escapes, so they show the art plain.
• Art wider than the transcript is cut at the right edge with an ellipsis and a line saying how many columns are missing. Widen the terminal.
• A state diagram’s [*] start and end are left out, because the renderer would draw them as empty boxes. A source longer than 12,000 characters keeps its fence.