Vistaro
vistaro.dev: the website, with the demos and a live tour of every animation.
A command-line tool for the AI coding agents that run on your machine: Claude Code, Codex, Antigravity. Ask your agent for a demo video, a help article or a marketing clip of your web app. The agent writes two text files, a mockup of the screen and a timeline of what happens on it, and the CLI turns them into the video and the guide. When the interface changes, you run it again. Agents: start with AGENTS.md, the manual with every file format.
Under the hood, the CLI drives a headless browser through the timeline. It moves a cursor, clicks, types and zooms, and records what it sees. You get an MP4 with subtitles and chapters, a numbered guide with a screenshot for every step, and the same again in each language you add. None of this needs an API key.
In: the two files of the sample in demo/. index.html is the screen and vistaro.config.json is the timeline.
Out: a 21-second MP4 with subtitles and chapters (watch it on vistaro.dev),
and a guide with one numbered frame per step, cropped to whatever the reader has to click:
Both come out of one command: npx vistaro export demo -o demo.mp4 --guide (see Quick start).
Why not just record your screen
Because the recording is out of date the day the product changes. Then you record it again by hand, in one language, and nobody can review what changed. Here a demo is two text files in your repository, so:
- The UI moved? Run the command again.
build-all --changed-only rebuilds only what changed and tells you which guides' screenshots drifted.
- The video and the written guide come from the same timeline, so they can't disagree.
- A new language is a translated strings file. The clicks, timings and camera moves are shared.
- The timeline is JSON, so it goes through a pull request like any other change, and the whole pipeline runs headless in CI.
- Marketing clips work the same way. A homepage animation is a timeline that gets reviewed and regenerated, not a video file someone re-cuts by hand. It usually gets its own mockup, since a marketing shot frames the product to make a point while a guide follows the real screens, but it uses the same tool, the same actions and the same translation path.
What you get
- Video: an MP4 (or GIF) with a moving cursor, a spotlight and a click ripple on every interaction, plus typing, camera pushes and screen transitions. Subtitles are drawn on the frame at about 4% of its height and move out of the way of the cursor and whatever is highlighted on their own (
meta.subtitleScale resizes them, a step's subtitlePlace pins one). You also get a .vtt file, MP4 chapters per step and, optionally, narration (OpenAI TTS or macOS say).
- Step guide:
guide.json, guide.md and guide.html, with a numbered frame and a crop per step, the video inline, and the measured timings.
- Languages:
localize scaffolds locales/<code>/ with a strings.<code>.json. Only the text changes between languages.
- Batch builds:
help.catalog.json plus build-all builds every guide in every language into one output tree with an index.json, skipping what hasn't changed and flagging guides whose frames drifted.
- Live pages:
record drives your real app from the same timeline, with real navigation, waits for async loads, and a saved login.
- Marketing reels: set
"kind": "reel" in the timeline. The spotlight, ripple and subtitles switch off, the clip is silent, and export gives you an MP4, a WebM, a poster and a GIF. If you turn subtitles back on ("reel": { "subtitles": true }), they render as a solid caption bar that stays readable in a muted autoplay clip. build --embed writes a self-contained embed-<device>.html that starts playing when scrolled into view and loops, plus the snippet for the page that hosts it. One responsive mockup covers desktop and phone, with per-device overrides in the timeline.
A step in the generated guide.md looks like this:
## 2. Check what is left
> Two of five sections are drafted.
Setup
In your project:
npm install --save-dev vistaro
npx playwright install chromium # one time: the browser Vistaro records with
npx vistaro --help
Or once for the whole machine with npm install -g vistaro (then vistaro --help), or without installing anything with npx vistaro@latest <command>. Run the Chromium line in every case: npm 12 and pnpm skip install scripts by default, so the download usually does not happen on its own. If it is missing, the CLI stops and prints the command to run. The same npm skips ffmpeg's download too; the first export fetches it on its own before recording.
Node >= 20.6, macOS or Linux (Windows is untested). The manual is installed with the package at node_modules/vistaro/AGENTS.md. Optional keys in .env or the environment: OPENAI_API_KEY (narration; falls back to macOS say), GEMINI_API_KEY / ANTHROPIC_API_KEY (only for the standalone extract and animate commands).
Ask your agent
Open your project in Claude Code, Codex or Antigravity and paste this. The agent installs Vistaro if needed and learns the rest from its manual:
Install vistaro as a dev dependency (npm install --save-dev vistaro, then npx playwright install chromium), read node_modules/vistaro/AGENTS.md, and create a product demo of the main screen of the app. Explore what vistaro offers and use the appropriate animations and transitions. Display a cursor as needed.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
