Visual explainer pages can now talk back. Select a few words or click part of a diagram to comment or ask, and send one reply to your agent; in Pi it lands straight in the chat. Plans, diff reviews, recaps, and the new /compare end with questions you answer in the page, so your reply tells the agent what to do next. Pages are also much cheaper to make: agents use about 60% fewer tokens to make one, so pages come back faster and revisions are small edits. And /generate-video turns an explainer into a narrated MP4.
Highlights
- Talk back to any page. Comment on selected words or a part of a diagram, then send one reply. In Pi it goes straight into the chat; elsewhere it is copied for you to paste.
- Plans you answer in the page.
/generate-visual-plandraws the change, lets you pick options and mark the agent's guesses, and sends back one response. After the build, the same page shows what was built. - Narrated videos.
/generate-videomakes a 1080p MP4 with voice-over, or records a walkthrough of a live web app. - Animated state machines. An explainer about a job queue, a workflow, or anything else with states can replay it one event at a time: the route lights up, a dot travels along it, queues fill and drain, and each caption says why it happened. Inspired by the animated state-machine diagrams in hapsland by Igor Loskutov (@dearlordylord).
- About 60% fewer tokens. An agent reads about 60% less guidance and writes about 60% less per page, so pages cost less and come back faster. Revisions are small edits instead of rewrites.
Need to know
--quick is gone. Drop it from any saved prompts; the same commands now make a full page, which costs about as little and gets replies, the four looks, and the page checks. MCP clients that called visual_explainer_render_quick should use visual_explainer_render_html.
Changelog
Highlights
- Talk back to any page. Select words or click part of a diagram to comment or ask, then send one reply. In Pi it goes straight into the chat; elsewhere it is copied for you to paste.
- Plans you answer in the page.
/generate-visual-plandraws the change, lets you pick options and mark the agent's guesses, and sends back one response. After the build, the same page shows what was built. - Narrated videos.
/generate-videoturns an explainer into a 1080p MP4 with voice-over, or records a walkthrough of a live web app. - Animated state machines. An explainer about a job queue, a workflow, or anything else with states can replay it one event at a time: the route each event takes lights up, a dot travels along it, queues fill and drain, and each step's caption says why it happened. Inspired by the animated state-machine diagrams in hapsland by Igor Loskutov (@dearlordylord).
- About 60% fewer tokens. An agent reads about 60% less guidance for a diagram and writes about 60% less per page, the always-on tool descriptions in Pi and MCP are shorter, and revisions are small edits instead of rewrites.
Added
/generate-videomakes a narrated MP4. The agent writes a video deck whose scenes carry their narration, andvisual-explainer-videorecords it at 1080p on a virtual clock, so motion never stutters and each picture appears with its sentence. Narration comes from ElevenLabs, Seed Audio, OpenAI, or xAI when a key is set; without one, the video is silent with captions.--stillssaves one picture per scene to check first. The same command can record a walkthrough of a live web app. It needs ffmpeg andplaywright-core, which you install separately so everyone else's install stays small./generate-visual-planmakes a plan you answer in the page instead of a page you only read. It opens on the change as a drawing whose numbered parts match a short list of claims. You pick options for the decisions the agent cannot make alone, mark its guesses right or wrong, comment on any words you select, then approve or request changes. Changing an option redraws the figure. Keyboard shortcuts and saved answers make long plans quick to get through.- After the build, the same plan becomes a receipt: each claim shows whether it was built, changed, or dropped, next to the check that proves it.
- Plans are written with a few short tags. The renderer reads the cited code from your repository and stops on file paths or line numbers that do not exist. Boxes-and-arrows diagrams (
<ve-flow>) are laid out for the agent, so it no longer places coordinates by hand. /comparedraws two or more options side by side, recommends one, and lets you pick in the page; your pick comes back to the agent in the reply.- Any page can be answered, not only plans. Select words or click part of a figure to comment or ask, and a quiet Reply button gathers your notes into one reply.
<ve-ask>puts a question with options on any page, and your answer joins the reply. In Pi, a page opened in a Glimpse window sends the reply straight into the chat when you press Send to agent; elsewhere it is copied for you to paste. - Diagrams carry their numbers and notes on the drawing. A wait, a size, or a time window is drawn as a dimension line on the span it measures. Numbered callouts match the steps of a step-through. A finding that lives in one small part, such as file permission bits, gets a close-up of that part.
- A step-through can replay a state machine one event at a time. The whole machine stays drawn while each event lights the route it took and dots run along it. Queues fill and drain, worker slots fill and free up, and counts change in place. Each caption says why the event happened and cites the code behind it.
examples/replay-job-queue.htmlshows all of it. <ve-bars>,<ve-waffle>, and<ve-stack>turn a few numbers into a chart, with units on every label and one scale across charts that share amax.<ve-flow>works on any page too. Hand-drawn diagrams stay the default.- Pages are written as a short source,
<name>.src.html, with one kit line in its head; the renderer adds the shared styles, fonts, diagram parts, and script. The reference page takes 64% fewer tokens to write, and renders the same. Pirenderand MCPvisual_explainer_render_htmltake the source aspath; elsewhere, runnode kit/render.mjs <name>.src.html. - Revisions, including
/fact-checkcorrections, are small edits to the kept source and a new render; the agent never writes the whole page again. - One kit carries all four looks.
data-registeron<html>picks Instrument, Blueprint, Paper, or Editorial, with its fonts and light and dark colors. - Every render reports its figures, uncaptioned figures, tags, and prose words in one line, and a mistake in a tag stops the render and names its line.
node kit/check.mjs page.htmlopens the page in Chrome at phone and desktop widths and reports script errors, sideways scrolling, and labels under 12 px. - The MCP server serves the skill's reference docs as resources, so a client that cannot read files can follow them.
Changed
/plan-reviewwrites its review as a plan page: each finding comes with evidence from the code and a suggested fix you accept or reject, and your answers come back as one response./diff-reviewasks about each risk worth fixing, so your reply comes back as the list of fixes to make. On someone else's PR it drafts review comments and never posts them./project-recapends by asking where to start. Both chart sizes and churn with the new data tags.- The guidance an agent reads for a diagram is about 60% shorter, and the always-on tool descriptions in Pi and MCP are shorter too.
- A page opened in a Pi Glimpse window now closes when the session ends, as plan windows do.
- A printed page uses its own look's colors on white, not the default amber.
Removed
--quickmode, along with Piaction: "render_quick"and MCPvisual_explainer_render_quick. A full page now costs about as little to write, and it gets replies, the four looks, and the page checks that quick pages lacked. Drop--quickfrom any saved prompts.
Fixed
- Section navigation on narrow screens no longer shows a grey scrollbar under the links. The links scroll with a faded edge, and buttons such as a skim toggle stay in place.
- Sources at the end of a page are always visible, in their own section at full size, instead of hidden behind a small grey toggle.
- In Pi, pressing Send to agent in a Glimpse plan window after
/new,/resume,/fork, or/reloadno longer crashes pi. Thanks to @masonc15 for #112. - A
VISUAL_EXPLAINER_OUTPUT_DIRthat passes through a symlink is now rejected before the directory is created, and the error shows where the path really leads, such as/private/tmpfor/tmpon macOS. The default~/.agent/diagrams/still follows a symlinked~/.agent. Thanks to @tharanee-bit for #115. - Pages that use
$$outside math, such as a$$query helper in a script or prices like$$5, no longer break on render. Thanks to @tharanee-bit for #115. - The reference page's small failure-mode diagrams drew their lower labels at 11.4 px on wide screens; they are now 12.3 px or more at every width.