/viz — self-portrait

/viz is a skill that lets an AI coding agent show you something — a chart, a graph, a 3D scene, a state machine, a dashboard, an animated explainer — as a live, hot-reloading web page instead of a wall of text. This page is that skill rendering itself: read it here, then open the Dashboard to watch the real running system.

The problem

You ask your AI assistant to “show me how these services talk,” or “visualize this distribution,” or “draw the state machine.” What comes back?

• ASCII art in the terminal that falls apart past ten boxes,
• a static SVG blob you can’t poke at, dumped into the chat and gone by the next message, or
• “I can’t really visualize that here.”

The terminal can’t render a real graph. Chat artifacts are throwaway and stateless. And there’s no loop — no way for the agent to make a picture, actually see how it came out, and fix it.

The solution

Give the agent a real browser canvas. /viz serves whatever HTML/CSS/JS it writes at a live local URL that hot-reloads on every save, keeps every version in git, and lets the agent screenshot its own output to check the render. One skill turns “describe it in words” into “build it, see it, refine it” — for anything HTML and JS can express, which is basically anything.

Same reason a whiteboard beats a paragraph: some ideas are shaped like pictures.

How it works — the 20-second version

A single tiny Bun web server runs in the background and serves your visualizations from many folders at once: a central scratch library, plus any viz-pages/ folder inside your own repos. Each viz is a folder with an index.html (optionally a live data backend). Save the file → the browser reloads itself. When you’re happy, one command bakes a viz into a single self-contained HTML file you can host anywhere.

You never have to hold any of this in your head — the agent drives it. Want the full picture? The architecture diagrams below break down the runtime and publish lifecycle; the Dashboard shows it running live.

Install it — however you like

Easiest, and it works across Claude Code, Codex, Copilot, Cursor, Gemini Antigravity, and more:

npx skills add RascalTwo/explorables

That drops /viz into every agent you have installed; update anytime with npx skills update. Prefer no third-party tools? Clone the repo and copy or symlink the skills/viz/ folder into your agent’s skills directory by hand — it’s fully self-contained. The only requirement is Bun.

Invoke it — every way there is

Once installed, just describe what you want to see. The plainest form:

/viz a force-directed graph of this repo's imports

• /viz <describe anything> — the agent names a spatial form and builds it.
• /viz [name] — hand it a slug, or let it choose one.
• --deck — an arrow-key slide deck instead of a single screen.
• --poster — a single 1200×630 share card (an OG image that unfurls in Slack/X/Teams).
• --local [dir] — create the viz inside a project’s repo, versioned with its code, rather than the central library.
• --global — force the central library even when you’re inside a repo.

And you never start from scratch twice — just talk to it: “color the bars by team,” “add a legend,” “make it 3D,” “now animate the transition.” Each ask edits the same viz and hot-reloads.

The feedback loop is the point

This is what makes it more than a code generator:

• Hot-reload — save and the page refreshes itself; you and the agent watch it change together.
• Self-verify — the agent drives headless Chrome to screenshot the viz and read its own console, catching a blank page or an overflowing label before handing it to you.
• Point at it — Alt/Option-click any element in the live viz to pin a comment to that exact bar or node; the agent reads your located feedback and fixes it. You review, it resolves.

Walkthrough — make your first viz

The fastest way to learn the whole tool is to make one thing. Here’s the arc, and the feature each step quietly teaches:

1. Ask for it bootstrap

   Say “/viz the states of a checkout flow as a state machine.” The agent scaffolds a viz folder, starts the server if it isn’t running, and hands you a live URL. You installed and configured nothing.

2. Watch it pick a form visual grammar + kit

   It announces the spatial form first — “rendering this as a state diagram, transitions as labeled arrows” — because a real shape (graph, treemap, Sankey, timeline) beats text in a box. It pulls from the built-in kit so colors and arrows look like one system, not re-guessed hexes.

3. See it — and see it checked verify

   Before it says “done,” it screenshots the page and reads the console, so “blank page from a typo’d import” gets caught and fixed, not shipped. You just get a working picture.

4. Refine by talking iterate + hot-reload

   “Mark the retry state red. Add a cancel transition.” Same viz, edited in place, browser reloads on save. Every change is committed to git, so any version rolls back.

5. Point at what’s wrong review layer

   Alt-click the “paid” node, type “this should loop back to cart on decline.” The pin sticks to that node even as things animate; the agent reads it, fixes it, marks it resolved.

6. Give it live data backend + tape

   Optional: a per-viz Bun api.ts feeds real data (a shell command, a file) streamed into the page. A tape recorder freezes a snapshot so it still plays away from your machine.

7. Ship it publish

   One command bakes the viz into a single self-contained HTML file for any static host — public, or encrypted behind a share-link or a one-password whole-site lobby. Its URL even unfurls a preview card.

That’s the spine. Everything else is depth on one of these steps.

…and there’s more than fits here

A sampler of what the agent can reach for — you don’t need to remember any of it:

Now go watch the machine run itself → open the Dashboard, which is this very page reporting on its own live server, roots, and history.

Install, then ask for a picture. Under a minute.

1 · Install

Needs Bun (bun --version should print a number). Then, in a terminal:

npx skills add RascalTwo/explorables

Works across Claude Code, Codex, Copilot, Cursor, Gemini Antigravity, and more — it installs /viz into each agent you have. Update later with npx skills update. (No npx? Clone the repo and symlink skills/viz/ into your agent’s skills dir.)

2 · Invoke

In your agent, just describe what you want to see:

/viz a treemap of this folder's file sizes

It picks a form, builds it, and hands you a live, hot-reloading URL.

3 · Loop

• Ask — /viz <anything>
• See — open the URL; it reloads as the agent edits
• Refine — “make it 3D,” “color by team,” or Alt-click an element to pin a comment

That’s the whole rhythm. Extras when you want them: --deck (slides), --poster (share card), --local (a viz inside a repo), a live api.ts backend, and one-command publishing.

Want the why, the how, and a guided tour? → read the full README. Or just poke the Dashboard.