visual-explainer: an agent skill that renders terminal output as HTML

The problem visual-explainer targets: ASCII art in agent replies

Coding agents default to text when asked for a diagram. The README puts the failure plainly: box-drawing characters, monospace alignment hacks and text arrows work for a three-box flowchart, and anything larger becomes unreadable. Tables have the same ceiling. A comparison of fifteen requirements against a plan arrives as pipes and dashes that wrap and break in the terminal.

The data is usually correct. The rendering is the problem. visual-explainer is an agent skill, not a standalone application, so it changes what the agent produces rather than adding a separate tool you run by hand. You ask for an explanation of an authentication flow, a diff review, or a plan audit, and the agent writes a self-contained HTML page and opens it in a browser.

The audience is narrow and specific. This is for engineers who already work inside an agent harness and who read the agent's output as part of review work: a diff that needs a second pass, a refactor plan that needs to be checked against requirements, a project recap that needs structure. It is not a charting library and it is not a reporting service. If you never ask your agent for a diagram, the skill has nothing to act on.

How the skill produces an HTML page: prompts, tools and render actions

The repository is organised around a canonical skill directory under plugins/visual-explainer/, with command templates in a commands subdirectory. The README describes the output as self-contained HTML with dark and light themes and interactive Mermaid diagrams with zoom and pan. Normal skill use has no build step and no dependency beyond a browser; the optional MCP and PPTX utilities pull in small Node dependencies.

The Pi integration is the most explicit about the mechanism. The package manifest advertises an extension, the skill directory, the prompt templates and a banner image. That extension registers one native tool named visual_explainer with two primary actions. The prepare action plans a visual explanation after the agent has generated or reviewed a substantial plan, architecture, diff or implementation. The render action writes complete HTML pages to ~/.agent/diagrams/. There is a third, opt-in action called render_quick that validates a compact JSON spec and renders it with a bundled local renderer.

Viewer selection is a parameter rather than a hardcoded behaviour. Render actions open with viewer: "browser" by default, viewer: "glimpse" when glimpseui is installed, or viewer: "auto" to try Glimpse and fall back to the browser. The split between prepare and render matters: the agent first decides what the explanation should contain, then a separate step writes the file. That gives you a chance to inspect the plan before anything is rendered.

Installing visual-explainer in Claude Code and Pi

Claude Code is the shortest path. The plugin marketplace commands add the repository and install the plugin:

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

The README notes that Claude Code namespaces plugin commands, so the bundled commands are invoked as /visual-explainer:command-name rather than bare names.

For Pi, the package install pulls the repository directly:

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

From a local checkout the README gives a two-step clone and install:

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

There is an upgrade hazard worth reading before you install. If you previously used the old curl installer, the user-level copies shadow the package resources and Pi reports skill and prompt conflicts. The README lists the files to remove first:

rm -rf ~/.pi/agent/skills/visual-explainer
rm -f ~/.pi/agent/prompts/{diff-review,fact-check,generate-slides,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 files over package management, but the README states it does not install the native Pi tool. For a first real use, the README's own examples are the safest starting point: ask the agent to draw a diagram of a flow, or run /diff-review, or run /plan-review against a markdown file. What you should see is a generated HTML page opening in your browser, not a terminal table.

MCP hosts, the output jail and the symlink rules

The MCP server is a separate entry point. It is local stdio only, and the README is explicit that it does not call an LLM, start an HTTP listener, handle credentials, or write outside its configured output directory. That directory defaults to ~/.agent/diagrams/ and can be moved with the VISUAL_EXPLAINER_OUTPUT_DIR environment variable. Unset, the default path is byte-identical.

The confinement rules are stricter than a typical output directory. A configured jail must resolve to itself, so symlinked jail paths are rejected. Render targets reject existing symlinks and are written through a temporary file rename. The README recommends pointing the jail at a directory only your user can write, and warns against world-writable or group-writable shared folders, because another local user could otherwise replace render targets between validation and write.

Configuration differs depending on whether you installed from a package or a checkout. A package install points the host at the binary:

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

From a checkout, the README says to run npm install --no-package-lock first, then point the host at plugins/visual-explainer/mcp/server.mjs with node, and notes that some hosts need an absolute path to the binary. The server exposes three tools: visual_explainer_prepare, visual_explainer_render_html and visual_explainer_render_quick. Render tools default to open: false, so a host will not pop a window unless you set open: true.

Where visual-explainer is the wrong tool

The MCP server does not call an LLM. It renders what it is given. If you expect the server itself to look at a diff and decide what matters, that decision belongs to your host agent, and the quality of the page depends on the skill instructions your agent loaded. A host that ignores skill resources will produce nothing useful here.

The PPTX path is explicitly best-effort. The README describes visual-explainer-pptx as a static utility that converts simple HTML slide decks to .pptx, and states that HTML remains the source of truth. Treat the PowerPoint file as a handoff artefact, not a format you round-trip. Nothing in the documentation describes importing a .pptx back into the pipeline.

The output jail is a real constraint for shared machines. Symlinked jail paths are rejected and render targets reject existing symlinks, which means a perfectly reasonable setup where your diagrams directory is a symlink into a synced folder will not work. On a multi-user box, a world-writable or group-writable output directory is called out as unsafe by the README. In CI, the browser-opening behaviour is also a mismatch: render tools default to open: false over MCP, but the point of the skill is a page a human reads. If nobody is reading, a deterministic text report is the better fit.

How visual-explainer compares with Mermaid CLI and plain markdown

The closest comparison is Mermaid CLI, and the difference is who composes the document. With Mermaid CLI you write the diagram source yourself and the tool renders it. visual-explainer inverts that: the agent decides what the explanation contains, and the skill supplies the styling, themes and interactive Mermaid rendering around it. If your diagrams are hand-authored and version-controlled, Mermaid CLI gives you a stable source file and a reproducible build. visual-explainer gives you a page generated from a conversation, which is faster to produce and harder to diff.

Against plain markdown, the difference is the opposite trade. Markdown is readable in a terminal, greppable, and survives a code review without a browser. The README's own framing is that terminal output is painful to read past a certain size, and that is true for fifteen-row comparison tables. But markdown does not need a viewer parameter, an output jail, or a browser to be useful.

The honest split is by artefact lifetime. A diagram you will regenerate once, read once and discard suits visual-explainer. A diagram that lives in the repository and gets edited by hand suits a source-first renderer. The skill also bundles command templates for diff review, fact-check, slide generation, visual plan generation and project recap, which is a wider scope than a diagramming tool and closer to a review workflow.

Maintenance, licensing and what an upgrade costs

The repository is not archived and the last push was on 2026-08-28. Releases have been frequent: v0.9.0 on 2026-08-13, v0.10.0 on 2026-08-20, and v0.11.0 on 2026-08-28. The package version in package.json is 0.11.0, and there is a check:versions script that runs node scripts/check-versions.mjs, which suggests version consistency across the manifest and the plugin metadata is checked rather than assumed.

The licence is MIT, stated in both the README badge and the package.json license field. MIT permits commercial use and modification with the copyright notice retained; this is a description of the licence text, not legal advice, and you should read the LICENSE file in the repository for the actual terms. The bundled dependencies are @modelcontextprotocol/server, node-html-parser, pptxgenjs and zod, with @earendil-works/pi-coding-agent as a peer dependency. Those are the pieces you inherit if you install the MCP or PPTX utilities; the README states that normal skill use has no dependency beyond a browser.

The upgrade cost is concentrated in the install matrix rather than the code. The README documents separate paths for Claude Code, Pi, MCP hosts, Antigravity CLI, Codex CLI, OpenCode, Cursor, OpenClaw and VS Code Copilot, and several of them are described as copied directories under a user-level skills path. The Pi section documents a concrete conflict when old curl-installed files shadow package resources, which is the failure mode to expect if you have installed this skill more than once on the same machine.

Editorial conclusion

Adopt visual-explainer if you already drive a coding agent through Pi, Claude Code, Cursor or an MCP host and you are tired of reading box-drawing tables in a terminal. Skip it if you need a deterministic renderer in CI or you cannot give the MCP output jail a directory only your user can write, because the server rejects symlinked jail paths and writes render targets through a temporary file rename. Before rolling it out, run the Claude Code marketplace install or pi install, then ask for a diagram of a flow you already understand and check whether the generated page matches it. The last push to the repository was on 2026-08-28.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. nicobailon/visual-explainer on GitHub
4. README
5. Releases