---
slug: "pi-grok-mermaid"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/RunMintOn/pi-grok-mermaid@main/README.md"
repo: "https://github.com/RunMintOn/pi-grok-mermaid"
source_file: "README.md"
branch: "main"
---
# pi-grok-mermaid🧜‍♀️

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

<table>
  <tr>
    <td width="50%"><img src="./image.png" alt="Mermaid diagram rendered in Pi"></td>
    <td width="50%"><img src="./picture1.png" alt="Mermaid fallback in a narrow terminal"></td>
  </tr>
  <tr>
    <td align="center">Rendered diagram</td>
    <td align="center">Narrow terminal fallback</td>
  </tr>
</table>
   
```text
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](https://github.com/xai-org/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](https://simonwillison.net/2026/Jul/16/grok-mermaid/)
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](https://tools.simonwillison.net/grok-mermaid). 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`](https://github.com/RunMintOn/pi-grok-mermaid/blob/HEAD/vendor/VENDOR.md), with the full upstream license in
[`vendor/LICENSE.grok-mermaid`](https://github.com/RunMintOn/pi-grok-mermaid/blob/HEAD/vendor/LICENSE.grok-mermaid).

## Try it

Install via npm (recommended):

```bash
pi install npm:pi-grok-mermaid
```

Or from GitHub:

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

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

---

To develop or test from a local checkout:

```bash
git clone https://github.com/RunMintOn/pi-grok-mermaid
cd pi-grok-mermaid
npm install
npm test
npm run check
pi -e .
```

## 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`](https://github.com/RunMintOn/pi-grok-mermaid/blob/HEAD/vendor/VENDOR.md).