glowy

Mermaid diagrams in glow.

Glow shows ```mermaid blocks as source. glowy is a small wrapper that redraws them as box-drawing diagrams with mermaid-ascii, then hands the file to glow. Run glowy README.md, or alias it to glow and keep typing what you always have.

    ┌──────────┐     ┌──────────────┐      ┌───────────────┐
    │          │     │              │      │               │
    │ Open .md ├────►│ Has mermaid? ├─yes─►│ mermaid-ascii │
    │          │     │              │      │               │
    └──────────┘     └───────┬──────┘      └───────┬───────┘
                             │                     │
                             │                     ▼
                             │             ┌───────────────┐
                             │             │               │
                             └────────no──►│      glow     │
                                           │               │
                                           └───────────────┘

Install

brew install sheetgenius/tap/glowy

That pulls in glow and mermaid-ascii too. To have plain glow draw diagrams, add this to your ~/.zshrc (or ~/.bashrc):

alias glow=glowy

glowy always calls the real glow binary, so the alias is safe.

Without Homebrew

You need glow, mermaid-ascii and python3 (3.9+; the one that ships with macOS works) on your PATH.

curl -fsSL https://raw.githubusercontent.com/sheetgenius/glowy/main/glowy -o ~/.local/bin/glowy
chmod +x ~/.local/bin/glowy

Try it

glowy sample.md

sample.md has a flowchart, a subgraph, a sequence diagram, an ER diagram, and a pie chart (which isn't supported, so it stays as source).

What it does

• Draws graph/flowchart, sequenceDiagram and erDiagram blocks. Other diagram types are left as source.
• Fits diagrams to glow's width (your terminal width up to 120 columns, or -w). Glow wraps anything wider, so a left-to-right flowchart that still doesn't fit, or fails to draw, is redrawn top-to-bottom.
• Leaves Mermaid examples inside other code fences alone (for example a ````markdown block that shows Mermaid syntax).
• Reads piped input: cat notes.md | glowy -. When you name a file, it reads the file even if stdin isn't a terminal. That's the one place it differs from glow, which would otherwise hang in scripts and agent shells.
• Passes everything else straight to glow: all flags, files without Mermaid, and glow's file browser (glow with no arguments or a directory). Diagrams aren't drawn inside the file browser.

For AI agents

glowy helps agents that write Markdown for you check how it will actually look before handing it over.

• glowy guide prints what renders well, what glow hides or shows literally, which diagrams draw, and the width you read at.
• glowy preview FILE prints the exact layout as plain text, then lists problems: diagrams that didn't draw, and lines that will wrap. It exits 1 if there are any.

Both use the width you actually read at. Every time you run glowy in a terminal, it saves the width glow wraps at to ~/.cache/glowy/width.json: glow's default of up to 120 columns, your -w, or the full window with -w 0. With nothing saved yet, they assume 120. Pass -w to preview to check a different width.

Tell your agents by adding this to ~/.claude/CLAUDE.md (Claude Code), ~/.codex/AGENTS.md (Codex), or your project's AGENTS.md:

## Markdown handoffs: the user reads them with glowy
- Before writing a Markdown document for the user, run `glowy guide` and follow it.
- Before handing it over, run `glowy preview FILE` and fix the problems it lists.
- End your reply with the command to read it: `glowy -p /absolute/path/to/file.md`.

Related

• glowm gist: the same idea as a Bash script.
• atani/glowm: renders diagrams as real images on iTerm2, Kitty and Ghostty.
• mdview, termd: standalone terminal Markdown viewers with ASCII Mermaid.
• Upstream request for Mermaid in glow: charmbracelet/glow#342.

License

MIT