pi-grok-mermaid

A Pi extension that automatically renders fenced mermaid blocks as terminal-style Unicode diagrams.

Assistant output → Pi Markdown renderer → Unicode diagram

Only Pi's TUI display layer is patched. Assistant messages, session files, model context, JSON mode, RPC mode, and print mode remain unchanged. If rendering fails, Pi's normal fenced-code renderer is used.

Lineage and credit

This project is directly based on the Mermaid terminal renderer shipped in xAI's open-source Grok Build, not a new implementation of Mermaid parsing or diagram layout. Grok Build's xai-grok-markdown/src/mermaid.rs recognizes Mermaid fences and draws them as Unicode box art inside its terminal UI.

Simon Willison extracted that renderer from the larger Grok Build codebase, replaced its small ratatui dependency surface with a shim, and compiled it to a standalone WebAssembly module for his browser playground. This extension reuses Simon's WebAssembly artifact and applies the same idea to Pi's terminal Markdown renderer.

The work specific to this repository is the Pi integration: detecting mermaid code tokens at the TUI rendering seam, invoking the WASM module, mapping Grok's semantic styles onto the active Pi theme, managing extension reloads, and falling back safely to Pi's normal code-block rendering.

The renderer is copyright 2023–2026 SpaceXAI and licensed under Apache 2.0. Simon Willison's extraction and build details are preserved in vendor/VENDOR.md, with the full upstream license in vendor/LICENSE.grok-mermaid.

Try it

From a repository checkout:

npm install
npm test
npm run check
pi -e .

To install the local package globally:

pi install .

Or install it directly from GitHub:

pi install git:github.com/RunMintOn/pi-grok-mermaid

Then start or reload Pi and ask for a fenced Mermaid diagram.

Supported diagrams

The bundled Grok renderer supports:

• graph / flowchart, including subgraphs
• sequenceDiagram
• stateDiagram
• classDiagram
• erDiagram

Unsupported or over-wide diagrams use the upstream framed-source fallback. The renderer does not reflow an already laid-out diagram to fit a narrower terminal.

How it works

Pi's shared Markdown component already parses fenced blocks into code tokens. During a TUI session this extension wraps the component's internal renderToken() method and handles tokens whose language is mermaid. The wrapper invokes the bundled WebAssembly renderer synchronously and maps its semantic style roles onto the active Pi Markdown theme.

The patch is removed during session_shutdown, is guarded against duplicate installation, and delegates every non-Mermaid token to Pi unchanged.

Markdown.renderToken() is currently an internal Pi TUI method, not a public extension API. The extension therefore fails closed and falls back to normal code rendering if that internal seam changes in a future Pi release.

Vendored renderer

vendor/grok-mermaid.wasm is Simon Willison's WebAssembly extraction of xAI Grok Build's Mermaid terminal renderer. The exact source revision, artifact hash, source locations, copyright, and license are recorded in vendor/VENDOR.md.