visual-explainer Documentation

Technical Documentation: nicobailon/visual-explainer

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

visual-explainer

An agent skill that turns complex terminal output into styled HTML pages you actually want to read.

Ask your agent to explain a system architecture, review a diff, or compare requirements against a plan. Instead of ASCII art and box-drawing tables, it generates a self-contained HTML page and opens it in your browser.

> draw a diagram of our authentication flow
> /diff-review
> /plan-review ~/docs/refactor-plan.md

https://github.com/user-attachments/assets/55ebc81b-8732-40f6-a4b1-7c3781aa96ec

Why Copy Chapter

Every coding agent defaults to ASCII art when you ask for a diagram. Box-drawing characters, monospace alignment hacks, text arrows. It works for trivial cases, but anything beyond a 3-box flowchart turns into an unreadable mess.

Tables are worse. Ask the agent to compare 15 requirements against a plan and you get a wall of pipes and dashes that wraps and breaks in the terminal. The data is there but it's painful to read.

This skill fixes that. Real typography, dark/light themes, hand-drawn diagrams that animate and respond to the reader. Normal skill use has no build step and no dependency beyond a browser; optional MCP and PPTX utilities use small Node dependencies.

Step through a state machine one event at a time: the route each event took lights up, jobs pile into queues and drain, and each step says why it happened (example).

Install Copy Chapter

Claude Code (marketplace):

/plugin marketplace add nicobailon/visual-explainer
/plugin install visual-explainer@visual-explainer-marketplace

Note: Claude Code plugins namespace commands as /visual-explainer:command-name.

Pi:

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

Or from a local checkout:

git clone --depth 1 https://github.com/nicobailon/visual-explainer.git
pi install ./visual-explainer

The package manifest advertises the canonical skill, command templates, and Pi tool:

"pi": {
  "extensions": ["./plugins/visual-explainer/extension.ts"],
  "skills": ["./plugins/visual-explainer"],
  "prompts": ["./plugins/visual-explainer/commands"],
  "image": "./banner.png"
}

The Pi extension registers one native visual_explainer tool. Use action: "prepare" to plan a visual explanation after generating or reviewing a substantial plan, architecture, diff, or implementation, and action: "render" to render a page source (path) or complete HTML to ~/.agent/diagrams/, or to VISUAL_EXPLAINER_OUTPUT_DIR when set, with the same output jail as the MCP server. Render can open with viewer: "browser" by default, viewer: "glimpse" when glimpseui is installed, or viewer: "auto" to try Glimpse and fall back to the browser. /generate-web-diagram remains the bundled prompt template command.

If you previously used the old curl/manual installer, remove those copied files before using pi install; otherwise Pi will report skill and prompt conflicts because the user-level copies shadow the package resources:

rm -rf ~/.pi/agent/skills/visual-explainer
rm -f ~/.pi/agent/prompts/{compare,diff-review,fact-check,generate-slides,generate-video,generate-visual-plan,generate-web-diagram,plan-review,project-recap}.md
rm -f ~/.pi/agent/prompts/s[h]are*.md

The legacy installer still works if you prefer copied skill and prompt files over package management, but it does not install the native Pi tool:

curl -fsSL https://raw.githubusercontent.com/nicobailon/visual-explainer/main/install-pi.sh | bash

MCP:

Use visual-explainer-mcp from a package install, or run npm install --no-package-lock before pointing your host at plugins/visual-explainer/mcp/server.mjs from a checkout. Some hosts need an absolute path to the binary. The MCP server is local stdio only. It does not call an LLM, start an HTTP listener, handle credentials, or write outside its configured output directory (default ~/.agent/diagrams/). Set VISUAL_EXPLAINER_OUTPUT_DIR to move that jail to another directory on the same machine; unset keeps the default path byte-identical. A configured jail must resolve to itself, so symlinked jail paths, including macOS /tmp, are rejected before anything is created. The default directory follows a symlinked ~/.agent. Render targets reject existing symlinks and are written through a temporary file rename. Point the jail at a directory only your user can write; avoid world-writable or group-writable shared folders so another local user cannot replace render targets between validation and write.

Example package configuration:

{
  "mcpServers": {
    "visual-explainer": {
      "command": "visual-explainer-mcp"
    }
  }
}

Example checkout configuration:

{
  "mcpServers": {
    "visual-explainer": {
      "command": "node",
      "args": ["/absolute/path/to/visual-explainer/plugins/visual-explainer/mcp/server.mjs"]
    }
  }
}

The server exposes two tools: visual_explainer_prepare and visual_explainer_render_html. Render defaults to open: false; set open: true only when you want the server to request a browser or Glimpse window. It also exposes the bundled command templates as MCP prompts and the canonical SKILL.md, its references/*.md, the kit stylesheet, and command markdown as read-only resources.

Antigravity CLI:

Antigravity CLI is the supported Google successor path for consumer Gemini CLI workflows. It loads Agent Skills from .agents/skills/ at the workspace level or ~/.gemini/antigravity-cli/skills/ globally.

Global install:

git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer

mkdir -p ~/.gemini/antigravity-cli/skills
cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.gemini/antigravity-cli/skills/visual-explainer

rm -rf /tmp/visual-explainer

PowerShell (global):

/* Detailed source-code truncated for AI context efficiency. */

Workspace install:

git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer

mkdir -p .agents/skills
cp -R /tmp/visual-explainer/plugins/visual-explainer .agents/skills/visual-explainer

rm -rf /tmp/visual-explainer

PowerShell (workspace):

/* Detailed source-code truncated for AI context efficiency. */

Launch agy in the project and use /skills to confirm visual-explainer is discovered. Ask Antigravity to use the visual-explainer skill for diagrams, visual reviews, slide decks, and complex tables. Antigravity SDK projects can reuse the same SKILL.md content as an Agent Skill resource, but this repo does not ship a separate SDK wrapper. The bundled prompt templates remain reference markdown under plugins/visual-explainer/commands/; no separate Antigravity plugin adapter is included.

Codex CLI:

git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer

mkdir -p ~/.codex/skills ~/.codex/prompts
cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.codex/skills/visual-explainer

# Optional, only if your Codex build supports prompt templates:
cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.codex/prompts/

rm -rf /tmp/visual-explainer

PowerShell:

/* Detailed source-code truncated for AI context efficiency. */

Invoke with $visual-explainer or ask Codex to use the visual-explainer skill. If prompts are installed and supported, use /prompts:diff-review, /prompts:plan-review, etc.

OpenCode/opencode:

git clone --depth 1 https://github.com/nicobailon/visual-explainer.git /tmp/visual-explainer

mkdir -p ~/.config/opencode/skill ~/.config/opencode/command
cp -R /tmp/visual-explainer/plugins/visual-explainer ~/.config/opencode/skill/visual-explainer

# Optional command templates:
cp /tmp/visual-explainer/plugins/visual-explainer/commands/*.md ~/.config/opencode/command/

rm -rf /tmp/visual-explainer

PowerShell:

/* Detailed source-code truncated for AI context efficiency. */

Activate it by asking OpenCode to use the visual-explainer skill. Command-template behavior depends on the installed OpenCode/opencode build.

Cursor:

Cursor loads Agent Skills from ~/.cursor/skills/ globally and .cursor/skills/ at the workspace level. Copy the canonical skill directory there and Cursor discovers it from the name: field in SKILL.md.

Global install:

set -euo pipefail
tmp="$(mktemp -d "${TMPDIR:-/tmp}/visual-explainer.XXXXXX")"
dest="$HOME/.cursor/skills/visual-explainer"
parent="$(dirname "$dest")"
run=''
stage=''
backup=''
moved=0
installed=0
cleanup() {
  status=$?
  if [ "$status" -ne 0 ] && [ "$moved" -eq 1 ] && [ "$installed" -eq 0 ]; then
    if [ -e "$dest" ]; then mv -- "$dest" "$run/failed" || true; fi
    if [ -e "$backup" ]; then mv -- "$backup" "$dest" || true; fi
  fi
  if [ -n "$run" ] && { [ "$installed" -eq 1 ] || [ ! -e "$backup" ]; }; then
    rm -rf -- "$run" || true
  fi
  rm -rf -- "$tmp" || true
}
trap cleanup EXIT
if git clone --depth 1 https://github.com/nicobailon/visual-explainer.git "$tmp/repo"; then :; else
  status=$?
  echo "git clone failed with exit code $status" >&2
  exit "$status"
fi
mkdir -p "$parent"
run="$(mktemp -d "$parent/.visual-explainer-install.XXXXXX")"
stage="$run/staging"
backup="$run/backup"
cp -R "$tmp/repo/plugins/visual-explainer" "$stage"
test -f "$stage/SKILL.md"
if [ -e "$dest" ]; then mv -- "$dest" "$backup"; moved=1; fi
mv -- "$stage" "$dest"
installed=1

Workspace install:

set -euo pipefail
tmp="$(mktemp -d "${TMPDIR:-/tmp}/visual-explainer.XXXXXX")"
dest=".cursor/skills/visual-explainer"
parent="$(dirname "$dest")"
run=''
stage=''
backup=''
moved=0
installed=0
cleanup() {
  status=$?
  if [ "$status" -ne 0 ] && [ "$moved" -eq 1 ] && [ "$installed" -eq 0 ]; then
    if [ -e "$dest" ]; then mv -- "$dest" "$run/failed" || true; fi
    if [ -e "$backup" ]; then mv -- "$backup" "$dest" || true; fi
  fi
  if [ -n "$run" ] && { [ "$installed" -eq 1 ] || [ ! -e "$backup" ]; }; then
    rm -rf -- "$run" || true
  fi
  rm -rf -- "$tmp" || true
}
trap cleanup EXIT
if git clone --depth 1 https://github.com/nicobailon/visual-explainer.git "$tmp/repo"; then :; else
  status=$?
  echo "git clone failed with exit code $status" >&2
  exit "$status"
fi
mkdir -p "$parent"
run="$(mktemp -d "$parent/.visual-explainer-install.XXXXXX")"
stage="$run/staging"
backup="$run/backup"
cp -R "$tmp/repo/plugins/visual-explainer" "$stage"
test -f "$stage/SKILL.md"
if [ -e "$dest" ]; then mv -- "$dest" "$backup"; moved=1; fi
mv -- "$stage" "$dest"
installed=1

Ask Cursor to use the visual-explainer skill for diagrams, visual reviews, slide decks, and complex tables.

Optional legacy rule: add configs/cursor/visual-explainer.mdc to your Cursor rules if you prefer rules-based guidance over relying on skill discovery alone.

OpenClaw:

Use configs/openclaw/AGENTS.md as lightweight project guidance and copy or reference plugins/visual-explainer/ as the canonical skill source. No native OpenClaw plugin adapter is included.

VS Code Copilot / Copilot CLI:

Use configs/copilot/AGENTS.md as custom instructions or rules guidance. For VS Code, copy it into a supported workspace custom-instructions file, such as .github/copilot-instructions.md. For Copilot CLI, add it through the workspace instruction or rules setup supported by your installed version. Both read the canonical skill from plugins/visual-explainer/; this repository does not provide native Agent Skills support, a Copilot package, or a tested Copilot plugin adapter.

Commands Copy Chapter

The agent also kicks in automatically when it's about to dump a complex table in the terminal (4+ rows or 3+ columns) — it renders HTML instead.

Slide Deck Mode Copy Chapter

Any command that produces a scrollable page supports --slides to generate a slide deck instead:

/diff-review --slides
/project-recap --slides 2w

For a portable presentation file, add --pptx to /generate-slides or run the exporter after generating an HTML deck:

visual-explainer-pptx ~/.agent/diagrams/my-deck.html ~/.agent/diagrams/my-deck.pptx

PPTX export is best-effort and static. It extracts titles, text, bullets, simple tables, code blocks, and Mermaid source placeholders from <section class="slide"> elements. It does not preserve animations, reader navigation, responsive layout, custom fonts, live Mermaid/Chart.js/SVG/canvas rendering, or JavaScript behavior. Use the HTML deck for final fidelity.

https://github.com/user-attachments/assets/342d3558-5fcf-4fb2-bc03-f0dd5b9e35dc

Themes Copy Chapter

Ask for switchable themes, or name a palette, and the page gets a picker — colored dots for the palette and Aa chips for the font pair, both swapping live:

"explain this pipeline, use Gruvbox"
"diagram the auth flow, let me switch themes"

Eleven palettes ship with it: Dracula, Nord, One Dark, Catppuccin Mocha, Tokyo Night, Gruvbox Dark, Synthwave '84 (dark) and Solarized Light, GitHub Light, Catppuccin Latte, Gruvbox Light. The font chips offer the pairs the skill already recommends. Diagrams draw with the page tokens, so they always match the active selection. Set theme: or font: in visual-explainer.config.md to choose what loads first. Claude Code users can keep personal overrides in .claude/visual-explainer.local.md; shared project defaults should use the harness-neutral file.

The picker is opt-in. Pages that don't ask for one still get a single palette and font pair chosen to fit the content.

How It Works Copy Chapter

.claude-plugin/
├── plugin.json           ← marketplace identity
└── marketplace.json      ← plugin catalog
plugins/
└── visual-explainer/
    ├── .claude-plugin/
    │   └── plugin.json   ← plugin manifest
    ├── SKILL.md           ← workflow + design principles
    ├── extension.ts       ← Pi native tool
    ├── commands/          ← slash commands
    ├── kit/               ← shared page CSS and script, renderer, page check, vendored Pele for Mermaid
    ├── mcp/               ← local stdio MCP server
    ├── pptx/              ← best-effort static PPTX exporter
    ├── video/             ← MP4 renderer for video decks
    ├── references/        ← read on demand
    │   ├── style-guide.md (four registers, layout, figure rules, topic motif, your own CSS)
    │   ├── kit.md         (kit marker, parts, data tags, <ve-flow>)
    │   ├── diagrams.md    (hand-drawn SVG kit, dimensions, callouts, linked highlighting)
    │   ├── motion.md      (stepper, scene player, replay, live figures, three.js)
    │   ├── slides.md      (deck budget, engine contract, delivery check)
    │   ├── video.md       (video deck contract, script and look rules, voice clips, tutorials)
    │   ├── extras.md      (Mermaid, images, older recipes)
    │   └── themes.md      (11 palettes + runtime theme/font picker)
    └── templates/
        ├── page.html      (figure-first reference page, Instrument register)
        └── slide-deck.html (slide engine + reference deck)

Output: ~/.agent/diagrams/filename.html → opens in browser. The agent writes a short source, filename.src.html, that links the shared kit; the renderer builds the page from it and keeps it for small revisions. When Chrome and playwright-core are available, the renderer also checks the page in a browser and writes filename.sheet.png, a contact sheet of the first screen, the figures, and every step, which the agent looks at instead of taking its own screenshots. On request, the agent also writes filename.md as an AI-readable companion; it asks before replacing one. In Pi, agents can offer visual_explainer prepare after a substantial plan, architecture, diff, or implementation, then render to write and open the page. MCP hosts use the visual-explainer-mcp stdio server, whose render tool defaults to open: false.

Pages are figure-first: the first screen shows the answer as a picture and one sentence. Each page uses one of four registers (Instrument for reviews and metrics, Blueprint for architecture, Paper for concepts, Editorial for recaps and decks), each with fixed fonts, a contrast-checked palette, and one shared spacing and type scale. Terms in the text and parts of the figure light up together on hover. Diagrams are hand-drawn inline SVG, so they match the page and can step through a process. Mermaid is used only when you ask for it. Tables carry status chips, metrics get bars and sparklines, and prose follows a Simplified Technical English style.

Limitations Copy Chapter

• Generated HTML is portable and self-contained, but auto-opening depends on the harness, browser access, and sandbox rules.
• PPTX export is a static best-effort handoff. The HTML deck remains the source of truth for full visual fidelity.
• All harnesses write visual output to ~/.agent/diagrams/ unless the user asks for a different path. The Pi tool and the MCP server write to VISUAL_EXPLAINER_OUTPUT_DIR instead when it is set.
• Results vary by model capability.

Credits Copy Chapter

Borrows ideas from Anthropic's frontend-design skill and interface-design.

Mermaid diagrams are drawn by Pele from Obsidian (MIT), bundled in kit/vendor/.

License Copy Chapter

MIT

Overview (`eval/README.md`) Copy Section

Eval: compare two variants of the skill

Not shipped in the package. Methodology only; record results in docs/.

1. Check out variant A and variant B of the skill side by side (for example, two worktrees).
2. For each prompt in prompts.md, start a fresh agent with only that variant's skill loaded and no repository or web access. Save its page as <scratch>/A/.html (or B/), outside the repository. Use the same model and settings for both variants.
3. Score each directory: node eval/score.mjs <scratch>/A and node eval/score.mjs <scratch>/B (--json for machine output). The browser check needs playwright-core (npm install).
4. Judge each prompt's pair with judge.md, in a fresh session. Assign A and B to the two pages at random, and do not tell the judge which variant is which.
5. Compare: the agents' token use, the score tables, and the judge verdicts. Treat a variant as better only if it wins or ties on every prompt's correctness.

Overview (`plugins/visual-explainer/mcp/README.md`) Copy Section

Visual Explainer MCP server

This directory contains the local Model Context Protocol server for visual-explainer.

Scope Copy Chapter

The server is stdio-only. It is meant for MCP hosts that launch a local child process.
It does not start an HTTP listener, handle credentials, call an LLM, or store output outside the local machine.

Rendered files are written only inside the configured output directory. The default is ~/.agent/diagrams/. Set VISUAL_EXPLAINER_OUTPUT_DIR to move that jail to another directory on the same machine; unset keeps the default path byte-identical. A configured jail must resolve to itself, so symlinked jail paths, including macOS /tmp, are rejected before anything is created. The default directory follows a symlinked ~/.agent. Render targets reject existing symlinks and are written through a temporary file rename. Choose a directory only your user can write; avoid world-writable or group-writable shared folders so another local user cannot replace render targets between validation and write. Filenames must be basenames. Paths, traversal, control characters, and symlink targets are rejected.

Run from a package install Copy Chapter

{
  "mcpServers": {
    "visual-explainer": {
      "command": "visual-explainer-mcp"
    }
  }
}

Run from a checkout Copy Chapter

Install dependencies first:

npm install --no-package-lock

Then point the host at the server entry:

{
  "mcpServers": {
    "visual-explainer": {
      "command": "node",
      "args": ["/absolute/path/to/visual-explainer/plugins/visual-explainer/mcp/server.mjs"]
    }
  }
}

Exposed tools Copy Chapter

• visual_explainer_prepare: returns a recommended visual explanation flow. It does not write files.
• visual_explainer_render_html: validates a complete HTML document and writes it to the configured output directory (default ~/.agent/diagrams/).

Render defaults to open: false. Set open: true only when you want the server to request a browser or Glimpse window.

Exposed prompts Copy Chapter

The server exposes the bundled command templates as MCP prompts:

• generate-web-diagram
• generate-visual-plan
• generate-slides
• generate-video
• diff-review
• plan-review
• project-recap
• compare
• fact-check

Pass request to fill the template's $@ argument.

Exposed resources Copy Chapter

The server exposes read-only resources for the canonical skill, its references, the kit stylesheet, and command templates:

• visual-explainer://skill/SKILL.md
• visual-explainer://references/*.md
• visual-explainer://kit/kit.css
• visual-explainer://commands/*.md

Overview (`plugins/visual-explainer/pptx/README.md`) Copy Section

Best-effort PPTX export

visual-explainer-pptx converts a generated visual-explainer HTML slide deck into a static .pptx file.

The HTML deck remains the source of truth. This exporter is intentionally best-effort and supports simple decks with <section class="slide"> elements. It extracts slide titles, short text, bullets, simple tables, code blocks, and Mermaid source placeholders.

It does not preserve:

• animations or transitions;
• reader rail, outline, help, deep links, or resume state;
• responsive layout;
• custom web fonts;
• live Mermaid rendering, Chart.js, SVG, canvas, or JavaScript behavior.

Usage Copy Chapter

From a package install:

visual-explainer-pptx ~/.agent/diagrams/my-deck.html ~/.agent/diagrams/my-deck.pptx

From a checkout, install dependencies first:

npm install --no-package-lock
node plugins/visual-explainer/pptx/export.mjs ~/.agent/diagrams/my-deck.html ~/.agent/diagrams/my-deck.pptx

If you omit the output path, the exporter writes beside the input with a .pptx suffix.

Use the HTML output for final fidelity. Use the .pptx as a portable static handoff when a presentation file is required.

--- METRICS ---

• Files Extracted: 4
• Estimated Token Budget: ~6525 tokens
• Canonical Reference: https://codewiki.google/github.com/nicobailon/visual-explainer