[FEATURE] Introduce Mermaid rendering support in Claude Code for outputting diagrams/charts
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] This is a single feature request (not multiple features)
Problem Statement
I semi-regularly use Claude Code to explore and map out new codebases, provide information about poorly documented PRs.
Claude Code excels at this type of tasks and outputs general Markdown summary. I also quite often prompt it to generate simple and high level ASCII diagrams.
Whilst the content of the diagrams makes sense, diagrams often look misaligned and more importantly, give 1D feel (top to bottom). As seen here:
<img width="359" height="740" alt="Image" src="https://github.com/user-attachments/assets/40f16a38-1df3-46b2-9f6c-6946bd5306b7" />
Misalignment:
<img width="73" height="121" alt="Image" src="https://github.com/user-attachments/assets/c3f8b38b-e6cd-4050-a9ec-cd849e4046a0" />
I understand this is a limitation of how language models generate output, at least ATM.
Proposed Solution
Ideally instead of generating diagrams directly, Claude could generate diagrams using Mermaid markup. Like so:
graph TD
A[Enter Chart Definition] --> B(Preview)
B --> C{decide}
C --> D[Keep]
C --> E[Edit Definition]
E --> B
D --> F[Save Image and Code]
F --> BWhich produces (Github supports directly rendering Mermaid diagrams):
graph TD
A[Enter Chart Definition] --> B(Preview)
B --> C{decide}
C --> D[Keep]
C --> E[Edit Definition]
E --> B
D --> F[Save Image and Code]
F --> BOfficial Mermaid library supports rendering diagrams as SVG or PNG. Both of which can be tricky to display inside the terminals.
Luckily there exists an awesome project, mermaid-ascii, for rendering Mermaid diagrams as ASCII.
Integrating Mermaid -> ASCII rendering in CC would enable correctly and accurately generating pretty diagrams directly in Claude Code - similarly like Claude would generate them if prompted.
The system prompt should probably include instruction to generate diagrams using Mermaid markup
Alternative Solutions
Generating Mermaid diagrams directly still requires rendering them either using online editors or CLI tools which breaks the flow of exploring/conversing with CC.
Some users may not even be aware of tools like Mermaid exist, with the given solution, they don't, they're simply presented correct diagrams.
Priority
High - Significant impact on productivity
Feature Category
Interactive mode (TUI)
Use Case Example
Exploring codebases, poorly documented PRs.
Can be used whenever it's needed/easier to visualize a particular idea or concept - which I often find colleagues are using CC for.
16 Comments
This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.
The chart could well be rendered in the desktop app.
Hi @esafak @0xroko , this is a pain I've hit too — ASCII diagrams in the terminal don't always look great, and sometimes I need them rendered nicely for copy to design documents.
I built Snip which takes a different approach: instead of rendering Mermaid as ASCII in the terminal, Claude generates the Mermaid code and pipes it through, calling the Snip CLI. Snip renders it properly using the Mermaid library and pops it up as a visual diagram on your screen.
Additional feature: you can also annotate on it (add notes, circle things) and the feedback goes back to Claude as structured data if you want it to iterate. Works with any agent that can call a CLI or MCP. Integrates well with Claude code.
Do take a look and let me know if it would be useful for you or how it could be extended to fit your use case!
Below diagram is a mermaid diagram rendered:
<img width="1347" height="886" alt="Image" src="https://github.com/user-attachments/assets/e8fa82bd-dccd-4f94-99b3-d13f83e83ce9" />
+1. Confirmando que sigue ausente en Claude Code VS Code extension
2.1.145(2026-05-22):webview/index.js(4.8 MB) contiene 0 referencias amermaid,flowchart,sequenceDiagram, dynamic imports, o CDN externos. Mismo resultado en2.1.143y2.1.144.NOT_PLANNEDel 2026-02-27.bierner.markdown-mermaidno es viable: rompeEdit/Cascade Diffde Claude Code con"File has not been read yet"— issue #34607, también cerrado comoNOT_PLANNED.Net: hoy no hay path funcional para renderizar mermaid en el VS Code extension. ASCII (como nota el OP) se desalinea en flows con múltiples ramas.
Render SVG inline en el webview vía mermaid.js cerraría este gap. Como bonus, el output queda portable: el mismo bloque ``
mermaid`renderiza en GitHub, Notion, claude.ai web, y cualquier.md` con preview compatible.+1 for the VS Code extension as well.
The same issue applies to the Claude Code VS Code chat panel — Mermaid blocks
render as raw code, not as diagrams.
One angle that hasn't been emphasized yet: in a chat context, users frequently
need to quickly parse and absorb information on the fly. A rendered diagram
communicates structure and flow at a glance; a raw Mermaid block requires
mental parsing just to understand what's being shown. This overhead breaks the
conversational rhythm, especially during architecture discussions or code exploration.
The gap with claude.ai is noticeable — the web version renders diagrams natively,
and it genuinely changes how useful they are. Since the VS Code extension already
runs in a GUI environment (like Desktop), SVG rendering via mermaid.js seems
entirely feasible here too.
The Code/Preview toggle proposed in this issue would be a great solution.
we need this. Cursor and Github copilot have these 6 months ago, and they really make a difference in discussing architecture and designs.
+1 specifically for the VSCode extension chat panel.
Issue: mermaid fenced blocks in chat render as raw code with no SVG fallback. #20529 was the same ask scoped to VSCode and got auto-closed as stale, not resolved.
The Code/Preview toggle proposed in #52517 (Preview by default, source still accessible) would be the right pattern here. Same model output, same UX, whether you're in claude.ai web, the Desktop Code tab, or the VSCode extension.
Use case: I use Claude Code mainly for codebase exploration and architecture discussions, where the model frequently emits flow / sequence / class diagrams. Today those land as text walls and break reading flow — the choice becomes "don't ask for diagrams" or "copy-paste into mermaid.live", both of which undercut staying in the editor.
The bierner.markdown-mermaid workaround also isn't viable: per #34607
it conflicts with Claude Code's Edit/Diff flow.
Cursor and Copilot have shipped this. Parity feels overdue.
+1. This is sorely missed.
+1
+1
+1
+1
+1
f*ck
+1 — daily blocker for Solidity/DeFi work. Contract call chains, proxy
upgrade architecture, flash-loan attack paths all want Mermaid, and ASCII
misaligns on any multi-branch flow (exactly the OP's screenshot). The
rendering engine already exists — plan mode renders markdown tables,
headings, and code blocks fine (see #13600), so this is wiring, not new
work. Pair it with the #64643 passthrough hook so the SVG/PNG lands inline
without bloating the transcript. Please prioritize.
f*ck