RELATED 01
sideshow
A browser viewer where a coding agent posts diagrams, diffs and sketches and reads your comments on them
633GitHub stars
550/wknpm downloads
61popularity score
visual-explainer
Writes self-contained HTML pages for diagrams, diff reviews, plans and slide decks to a local folder
By Nico Bailon (individual) JavaScript Local · stdio Developer toolsDesign
81 popularity score ★ 11k ↓ 568/wk
Connect your client
Local (npm)
Add in one click
Opens the app, which asks before it adds the server.
Or add it by command or config
Claude CodeTerminal
claude mcp add visual-explainer -- npx -y -p visual-explainer visual-explainer-mcpClaude Desktopclaude_desktop_config.json
{
"mcpServers": {
"visual-explainer": {
"command": "npx",
"args": [
"-y",
"-p",
"visual-explainer",
"visual-explainer-mcp"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"visual-explainer": {
"command": "npx",
"args": [
"-y",
"-p",
"visual-explainer",
"visual-explainer-mcp"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"visual-explainer": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"-p",
"visual-explainer",
"visual-explainer-mcp"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.visual-explainer]
command = "npx"
args = ["-y", "-p", "visual-explainer", "visual-explainer-mcp"]Gemini CLITerminal
gemini mcp add --scope user visual-explainer npx -- -y -p visual-explainer visual-explainer-mcpLocal (from source)
Add in one click
Opens the app, which asks before it adds the server. Then replace each <NAME> in its settings with your value.
Or add it by command or config
FirstTerminal
git clone https://github.com/nicobailon/visual-explainer.git
cd visual-explainer
npm install --no-package-lockClaude CodeTerminal
claude mcp add visual-explainer -- node '<ABSOLUTE_PATH_TO_CLONE>/plugins/visual-explainer/mcp/server.mjs'Claude Desktopclaude_desktop_config.json
{
"mcpServers": {
"visual-explainer": {
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_CLONE>/plugins/visual-explainer/mcp/server.mjs"
]
}
}
}Cursor~/.cursor/mcp.json
{
"mcpServers": {
"visual-explainer": {
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_CLONE>/plugins/visual-explainer/mcp/server.mjs"
]
}
}
}VS Code.vscode/mcp.json
{
"servers": {
"visual-explainer": {
"type": "stdio",
"command": "node",
"args": [
"<ABSOLUTE_PATH_TO_CLONE>/plugins/visual-explainer/mcp/server.mjs"
]
}
}
}Codex~/.codex/config.toml
[mcp_servers.visual-explainer]
command = "node"
args = ["<ABSOLUTE_PATH_TO_CLONE>/plugins/visual-explainer/mcp/server.mjs"]Gemini CLITerminal
gemini mcp add --scope user visual-explainer node -- '<ABSOLUTE_PATH_TO_CLONE>/plugins/visual-explainer/mcp/server.mjs'Settings 1
VISUAL_EXPLAINER_OUTPUT_DIR |
Optional: Folder pages are written to and confined to. A configured folder must not be or pass through a symlink. |
|---|
What it does
visual-explainer is mainly an agent skill: a set of instructions, a shared page kit and command templates that tell a coding agent to present architecture overviews, diff reviews, plan reviews, project recaps, data tables and slide decks as styled HTML pages instead of ASCII art in the terminal. The same repository ships a small local MCP server, visual-explainer-mcp, so any MCP host can use it.
The server writes no content itself and calls no language model. The assistant writes a short page source (name.src.html) that links the shared kit, or a complete HTML document, and the server checks it, builds the final page and saves it in an output folder, ~/.agent/diagrams/ by default. Since version 0.14.0 there are two tools: one that plans an explanation and one that renders either a source file already in the output folder (path) or HTML passed inline with a filename. The quick-mode JSON tool of earlier releases is gone. For plan pages, citations are checked against a repository given as root, which defaults to the server's working directory. Each render returns a short report on the page (figure, caption, data-tag and flow counts, prose word count).
Beyond tools, the server offers nine command templates (diff-review, plan-review, fact-check, generate-slides and others) as MCP prompts, and serves SKILL.md, every file under references/, the kit stylesheet and the command markdown as read-only resources, so a host without file access can still load the design rules.
What it needs
| Runtime | Node.js |
|---|---|
| Runs on | macOS, Windows, Linux |
| Also |
|
Node.js to run the npm package through npx, or a checkout after npm install --no-package-lock. Optional extras the install does not bring: the Glimpse viewer needs glimpseui; the in-browser page check and contact sheet need Chrome plus playwright-core (an optional peer dependency, npm install playwright-core); video export also needs ffmpeg. No account or API key.
Limits
- Not covered Two tools only; it saves and checks HTML the assistant writes, so page quality depends on the model.
- Not covered Writes only inside the output folder; a filename must be a basename without '/', '\\' or '..', and .html is added when missing.
- Limit A configured output folder that is or passes through a symlink (including macOS /tmp) is refused, and existing symlinks at a target are rejected.
- Limit render_html takes either path or html with filename, never both; filename is refused alongside path.
- Limit Opening a page is off by default (open: false) and depends on the host's browser access and sandbox rules.
- Not covered PPTX and video export are separate programs (visual-explainer-pptx, visual-explainer-video), not MCP tools; PPTX is a best-effort static copy.
- Limit Some hosts need an absolute path to the visual-explainer-mcp binary.
Only three tools; the quality of pages depends on the model writing the HTML. Files are written only inside the configured output folder; a symlinked output folder (including macOS /tmp) is refused, and existing symlinks at a target are rejected. Opening a page depends on the host's browser access and sandbox rules. PPTX and video export are separate command-line utilities, not MCP tools; video export needs ffmpeg, Chrome and playwright-core installed separately. Some hosts need an absolute path to the binary.
Who it suits
Suits developers who want an assistant in any MCP host to hand back diagrams, review pages or slide decks as local HTML files they open in a browser, with no account, network service or key. Users of Claude Code, Codex, Pi or Antigravity can install it as a skill or plugin instead, which its README documents and which carries the full workflow; the MCP server is the route for other hosts, and the one for hosts without file access, since its resources carry the skill text. It is not a diagram editor or design-file tool: it only checks and saves pages the assistant has written.
Tools 2
1 only reads, 1 changes things. A ? marks an optional parameter.
visual_explainer_prepare- Returns a plan and recommended steps for an explanation from a topic, goal, audience and files; reads and writes nothing.
topic: stringgoal?: stringfiles?: arrayaudience?: string visual_explainer_render_htmlchanges- Builds a page from a source file or inline HTML, saves it to the output folder, reports on it and can open it.
filename?: stringhtml?: stringpath?: stringroot?: stringopen?: booleanviewer?: enum
Resources 4
visual-explainer://skill/SKILL.md- The skill's main instructions
visual-explainer://kit/kit.css- The shared page stylesheet
visual-explainer://references/{file}- Each reference file the skill points to (diagrams, kit, video and others)
visual-explainer://commands/{file}- The markdown of each command template
Prompts 9
compare- Command template for a comparison page
diff-review- Command template for a visual review of a diff
fact-check- Command template for checking a page's claims
generate-slides- Command template for a slide deck
generate-video- Command template for a video deck
generate-visual-plan- Command template for a visual implementation plan
generate-web-diagram- Command template for a diagram page
plan-review- Command template for reviewing a plan against the code
project-recap- Command template for a project recap