Mermaid diagrams in Claude Code

Claude often answers with Mermaid diagrams. With the termaid plugin, Claude Code draws them in your terminal as Unicode diagrams, while the reply streams.

Claude Code drawing an OAuth login sequence diagram as Unicode text in the terminal
Ask for a sequence diagram and Claude Code draws it in place.

Install the plugin

  1. Install the termaid command. The plugin runs it to draw each diagram.
    brew install termaid
    # or
    uv tool install termaid
  2. In Claude Code 2.1.275 or later, install the plugin:
    /plugin install termaid --marketplace fasouto/termaid
  3. On older versions, add the marketplace first:
    /plugin marketplace add fasouto/termaid
    /plugin install termaid@termaid

The plugin adds a MessageDisplay hook that runs termaid --claude-hook on each reply, and a /termaid:mermaid skill.

Ask Claude for a diagram

Ask for any Mermaid diagram in plain words. The hook holds back a mermaid code block until it closes, then draws the diagram where the code was. Text before and after it stays as Claude wrote it.

The hook only changes what you see. The transcript keeps the Mermaid source, so you can ask Claude to change the diagram in the next message and it redraws.

Claude Code draws a checkout flowchart, then redraws it with a payment retry step after a follow-up request
A checkout flowchart, then a follow-up: "Add a step that retries a failed payment once."

Explain your code with a diagram

Diagrams help most when Claude explains code you haven't read yet. Ask how something works and ask for the answer as a flowchart or sequence diagram.

Claude Code reads a source file and answers with a flowchart drawn as Unicode text
Claude reads the hook's source in the termaid repo and answers with a flowchart.

A database schema as an ER diagram

Claude Code reads schema.sql and draws an entity-relationship diagram with keys and cardinality
"Draw an ER diagram of schema.sql." Tables, keys and cardinality from four CREATE TABLE statements.

Python classes as a class diagram

Claude Code reads models.py and draws a class diagram with fields, methods and an enumeration
"Draw a class diagram of models.py." Dataclasses, an enum and their relationships.

Plan work as a gantt chart

Ask Claude to plan a release or a migration as a gantt chart and read the schedule in the terminal.

Claude Code drawing a six-week launch plan as a gantt chart with build, test and release sections
A six-week launch plan with build, test and release sections.

Draw the diagrams in a file

For diagrams that already exist, such as the ones in a README, a .mmd file or a pull request description, use the /termaid:mermaid skill.

The /termaid:mermaid skill drawing the flowchart and state diagram from a README in Claude Code
/termaid:mermaid show the diagrams in README.md draws a flowchart and a state diagram.

Without the plugin

The same hook works from .claude/settings.json, for a project that shouldn't depend on a plugin:

{
  "hooks": {
    "MessageDisplay": [
      { "hooks": [ { "type": "command", "command": "termaid --claude-hook", "timeout": 10 } ] }
    ]
  }
}

In scripts, pipe the output of claude -p through termaid --markdown, which draws every mermaid block in a Markdown document:

claude -p "draw the login flow as a mermaid sequence diagram" | termaid --markdown

Questions

What if termaid is missing or a diagram fails to draw?

Claude Code shows the original mermaid code block.

Which diagram types work?

termaid draws 18 Mermaid diagram types: flowcharts, sequence, class, ER, state, block, git graph, gantt, architecture, pie, treemap, mindmap, XY chart, user journey, packet, timeline, kanban and quadrant charts. See them all on the examples page, or try your own in the playground.

Does it work outside Claude Code?

Yes. termaid is a command line tool and a Python library. Run uvx termaid diagram.mmd, or read the README on GitHub for the Python API, themes and editor integration.