Visual Explainer: From Terminal Art to HTML Diagrams

Visual Explainer: From Terminal Art to HTML Diagrams

Introduction

Many developers still print complex terminal output as plain text, but ASCII art and pipe‑delimited tables quickly become unreadable. Visual Explainer turns any terminal diagram, code diff, or plan review into a polished, self‑contained HTML page—complete with dark/light theming, interactive Mermaid charts, and responsive slide decks.

The Problem

• Terminal ASCII art works for a single‑box flowchart but shatters with multi‑box diagrams.
• Tables rendered with | and - look great on the terminal but collapse or wrap badly when exported or shared.
• Preparing presentations or documentation from raw diff output is time‑consuming and error‑prone.

The Solution

Visual Explainer replaces the cluttered terminal output with a browser‑ready page that preserves structure, styling, and interactivity. It ships with several handy slash commands that automatically detect when you’re dumping complex data and render the best HTML representation.

Core Features

All commands trigger the same underlying workflow: the skill parses your request, chooses the right reference template, fetches required data from the references/ folder, and writes an HTML file in ~/.agent/diagrams/. The page auto‑opens in your default browser.

Installation

If you’re already a pi user, the installation is one line:

pi install https://github.com/nicobailon/visual-explainer

For users of Claude Code or other agents, simply clone into the skills directory:

git clone https://github.com/nicobailon/visual-explainer.git ~/.claude/skills/visual-explainer

No build step is required; the tool only relies on a browser and, optionally, the surf-cli binary for image generation.

Using the Skill

A quick demonstration:

generate-web-diagram
draw a diagram of our authentication flow

The skill will render a Mermaid diagram, apply a light/dark theme, and open the file ~/.agent/diagrams/auth-flow.html in your browser.

To review a recent pull request:

diff-review #42

By default, /diff-review compares the current branch with main. You can also pass arbitrary refs:

diff-review abc123            # single commit
diff-review main..HEAD         # all staged commits
diff-review main..dev-feature # entire branch

To create a slide deck from your diff review, add the --slides flag:

diff-review --slides

Customization

• Theme & Layout – edit the CSS files in references/css-patterns.md to choose palettes or tweak animations.
• Template – swap out any of the four templates in templates/ (e.g. architecture.html, data-table.html) or write your own.
• Output Directory & Browser – modify SKILL.md variables to change where files are written or how they are launched.

Because the skill reloads the templates each run, you can iterate quickly without restarting the agent.

Limitations & Trade‑offs

• No inline terminal rendering – the results open in a browser; you cannot see them within the terminal itself.
• Theme switching requires a page refresh – Mermaid SVGs do not automatically adapt to OS theme changes.
• Model‑dependent quality – the visual output depends on the underlying LLM’s ability to produce Mermaid or CSS code.

Despite these caveats, Visual Explainer significantly reduces the friction of converting raw text into meaningful visual artifacts.

Community & Support

The repo is actively maintained and features regular updates such as anti‑slop guardrails (v0.3.0). Issues, feature requests, and pull requests are welcome on GitHub. The 3.3 k stars reflect a growing developer community using the tool for everything from ad‑hoc diagrams to formal documentation.

Conclusion

Visual Explainer is a lightweight, open‑source developer utility that turns noisy terminal output into polished HTML pages or slide decks. With a handful of slash commands, you can auto‑generate architecture diagrams, diff reviews, plan audits, or presentation decks—all while keeping your workflow inside the agent environment. Give it a try and reclaim the visual clarity you deserve from your codebase.