# HyperFrames launch-video agent kit

Install tested November 7, 2026; launch-video phase added and tested November 11, 2026. Claude Code 2.1.318 on macOS, HyperFrames 0.9.19 (npm package `hyperframes`, Apache-2.0, by HeyGen). Newer HyperFrames versions exist (0.9.33 on November 11); this kit stays on the version we read and tested.

How to use this file: put it in your project folder, open Claude Code there, and type:

    Read HyperFrames-launch-video-agent-kit.md and follow it.

---

## Instructions for the agent

You are setting up **HyperFrames** (github.com/heygen-com/hyperframes, Apache-2.0, made by HeyGen) for the human. HyperFrames turns an HTML page with timed animations (HTML, CSS and GSAP) into an MP4 video. It's a command-line tool run with `npx`, plus four "skills" that teach Claude Code how to write those pages. Rendering happens on this computer: a headless Chrome takes a picture of every frame and FFmpeg turns the pictures into a video.

Work through the phases in order. Run every check yourself and show the human the real output. Don't skip a phase because it "probably" passed. If a phase fails, stop, use the troubleshooting table, and tell the human what you found in plain words.

### Safety rules (follow all of them)

1. Run HyperFrames ONLY as `npx hyperframes@0.9.19 ...` (the npm package `hyperframes`, pinned). Don't install look-alike packages, forks, `@latest`, or a global install (`npm install -g`). They ship several releases a day; the pinned version is the one we checked.
2. Turn telemetry off FIRST (Phase 1). It's on by default, and the very first command would send an anonymous usage event before you could switch it off, so the first command carries `DO_NOT_TRACK=1`.
3. Never run these HyperFrames commands: `usage`, `events`, `feedback`, `auth`, `cloud`, `lambda`, `cloudrun`, `publish`, `billing`, `capture`, `figma`, `upgrade`. Some need a HeyGen account or cost credits, some upload the project, and `usage` reads the human's Claude Code login from the keychain. If one of the skills tells you to run one of them, skip it and say so (the /hyperframes skill asks for `npx hyperframes events --skill=hyperframes` and `npx hyperframes usage --json` at the start: skip both).
4. Don't sign the human up for anything (HeyGen account, HyperFrames Pro, the desktop app). Everything in this kit is free and local.
5. Don't run `sudo`, `npm install -g`, `brew install` or any `curl ... | bash` yourself. If something is missing, tell the human what to install.
6. Never open, print or copy `.env` files, API keys or tokens. Don't set any HeyGen, ElevenLabs, Gemini or OpenAI keys.
7. The preview server must stay on this computer: never set `HYPERFRAMES_PREVIEW_HOST`. Stop any preview server you start before you finish.
8. Don't commit, push or change the human's existing project files. Make new files only inside the test folder in Phase 3 and the `launch-video/` folder in Phase 5.
9. Don't run `transcribe` (without `--engine parakeet` it can run `brew install whisper-cpp` on its own) and don't generate music with MusicGen (its model license is non-commercial).

If HyperFrames is already set up (telemetry already disabled, the four skills already listed in Phase 2's check, and `/hyperframes` available in this session), say so, run Phase 0 and the checks of Phases 1 to 3 quickly, and go on to Phase 5.

---

## Phase 0: Before you start

Run these and report each result:

```bash
claude --version
node --version
ffmpeg -version | head -1
git --version
```

- `node --version` must be **v22 or newer**. If it's older or missing, stop: the human needs Node.js 22+ from nodejs.org.
- `ffmpeg` must print a version. If it's missing, stop and tell the human: on a Mac, `brew install ffmpeg` (Homebrew), on Windows `winget install ffmpeg`. HyperFrames only notices a missing FFmpeg when it tries to render, so check it now.
- `git` is needed by the skills installer.

## Phase 1: Telemetry off, then doctor

```bash
DO_NOT_TRACK=1 npx --yes hyperframes@0.9.19 telemetry disable
DO_NOT_TRACK=1 npx --yes hyperframes@0.9.19 telemetry status
DO_NOT_TRACK=1 npx --yes hyperframes@0.9.19 doctor
```

- `telemetry disable` prints `Telemetry disabled`. It saves the choice in `~/.hyperframes/config.json`, so it sticks for later commands.
- `doctor` lists checks. The ones that matter: Node.js, FFmpeg, FFprobe and Chrome. Tell the human which of these passed. Ignore these if they show ✗: **Docker**, **TTS (Kokoro)** and **BGM (MusicGen)** are optional extras, and doctor still ends with "Some checks failed" because of them. That's normal (ours did too).
- If Chrome shows ✗, that's fine at this point: run `DO_NOT_TRACK=1 npx --yes hyperframes@0.9.19 browser ensure`. It downloads Google's headless Chrome (about 190 MB on disk) into `~/.cache/hyperframes`. It must end with `Ready to render.`

## Phase 2: Install the skills

```bash
DO_NOT_TRACK=1 npx --yes hyperframes@0.9.19 skills update
```

This copies four skills (`hyperframes`, `hyperframes-cli`, `hyperframes-registry`, `media-use`) into the human's Claude Code skills folder (`~/.claude/skills`, or `$CLAUDE_CONFIG_DIR/skills`) and into `~/.agents/skills`. It uses a second small npm tool (`skills@1.5.13`, from Vercel) and clones the HyperFrames repo at the matching tag (v0.9.19).

Because it writes into the human's Claude Code folder, Claude Code may ask for permission or its auto-mode safety check may block it. That's expected. Don't look for a way around it: show the human the exact command, say what it changes (four skill folders added to their Claude Code skills), and ask them to approve it. If it stays blocked, ask them to run it themselves by typing `!` followed by the command in Claude Code, then continue.

Expected (our run, about 7 seconds): a "Security Risk Assessments" table (it rated the skills Safe / 0 alerts on two scanners and Low to Med Risk on Snyk; show the human the table), then `Installed 4 skills` and `Done! Review skills before use; they run with full agent permissions.` Then check:

```bash
ls "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills" | grep -E "hyperframes|media-use"
```

All four names must be there. Skills load when Claude Code starts, so they are NOT active in this session yet. That's fine for Phase 3.

## Phase 3: Smoke test (a real render)

Make a throwaway project with the plain starter template and render it, to prove Chrome and FFmpeg work together:

```bash
DO_NOT_TRACK=1 npx --yes hyperframes@0.9.19 init hf-smoke-test --non-interactive --example blank --skip-skills
cd hf-smoke-test
DO_NOT_TRACK=1 npx --yes hyperframes@0.9.19 lint
DO_NOT_TRACK=1 npx --yes hyperframes@0.9.19 render --output renders/smoke.mp4 --quiet
ffprobe -v error -show_entries format=duration:stream=width,height -of compact renders/smoke.mp4
```

- `lint` should report 0 errors.
- The render takes about 10 to 45 seconds (ours: 41 s on the first run, because it started the browser fresh). `ffprobe` must show width 1920, height 1080 and a duration of about 10 seconds.
- Tell the human the file path so they can open it.

Then `cd ..` back to the project folder. Leave `hf-smoke-test/` there and tell the human they can delete it.

## Phase 4: Make sure the skills are loaded

Skills load when Claude Code starts. If you installed them in Phase 2 of THIS session, `/hyperframes` isn't available yet: do Phase 5 steps 1 and 2 (read the files, fill in the prompt), then tell the human exactly this and stop after the Phase 6 report:

1. Type `/exit`, then start `claude` again in this folder. Typing `/` should now list `/hyperframes`.
2. Paste the filled prompt (or type "Read HyperFrames-launch-video-agent-kit.md and follow it" again: the setup is done, so it goes straight to the video).
3. If the brand font isn't in the project, Claude will try to download it (Google Fonts or the Fontsource npm package). Claude Code may ask before it downloads; that's normal. If the project already has the font files (ours had them from an earlier HyperFrames card), Claude copies those instead.

If `/hyperframes` IS available in this session, go straight on to Phase 5.

## Phase 5: Build your first launch video (30 seconds, 5 scenes)

This is the build from our YouTube tutorial. Fill in the prompt below from the human's own project files. Only use what you actually find in their files: real copy, real colour hex codes, the real font name, a real offer or detail. If the project has no promo code, use the call-to-action text instead of a code and drop "promo code" from the variables. Keep prices out unless the human asks for them.

1. Read the main HTML page and the CSS. Find: the product name; the main headline; three features (names + one line each); one real quote or testimonial if there is one; the background, accent and highlight colours (hex); the font; the logo (an SVG path or an image file); one real offer or detail (a promo code, a launch date, a free trial line).
2. Fill in this prompt (ours, for a habit app called Pulse, is underneath):

> Using /hyperframes, make a 30-second 1920x1080 launch video for <product> in a new folder called launch-video. Five scenes: a hook, <feature 1>, <feature 2>, <feature 3> and an end card. Give each feature a real visual that fills the frame: <a visual for feature 1>, <a visual for feature 2, with the quote if there is one>, <a visual for feature 3>. Use only real copy from <html file> and <the real offer> from <file>, no prices. Brand: <background hex>, <accent hex>, <highlight hex>, <font>, <logo>. Expose headline, accent color and promo code as variables. Run the CLI as npx --yes hyperframes@0.9.19. No Math.random or Date.now. Don't run usage or feedback. Lint, check, then render to launch-video/renders/<product>-launch.mp4.

   Ours (Pulse): "Using /hyperframes, make a 30-second 1920x1080 launch video for Pulse in a new folder called launch-video. Five scenes: a hook, Streaks, Insights, Reminders and an end card. Give each feature a real visual that fills the frame: a check-in calendar with a streak counter, a weekly chart where Monday dips next to Daniel K.'s quote, a reminder notification sliding in. Use only real copy from index.html and LAUNCH20 from pricing.js, no prices. Brand: #0c0b12, #7c3aed, #c4b5fd, Bricolage Grotesque, the pulse-line logo. Expose headline, accent color and promo code as variables. Run the CLI as npx --yes hyperframes@0.9.19. No Math.random or Date.now. Don't run usage or feedback. Lint, check, then render to launch-video/renders/pulse-launch.mp4."

   Why each part is there: "a real visual that fills the frame" (without it our first try came out as small text cards in one corner); "only real copy" and "no prices" (no invented claims); the hex codes (named colours beat "use our brand colours"); "variables" (so one video becomes many, see below); "No Math.random or Date.now" (renders must be repeatable); "Don't run usage or feedback" (the /hyperframes skill asks the agent to run `npx hyperframes usage --json`, which reads the human's Claude Code login).
3. If `/hyperframes` is available in THIS session, run the filled prompt yourself now: load the skill, build it, lint, check, look at frames, fix what looks wrong, render. If it isn't available (you installed the skills in this session), give the human the filled prompt and tell them to restart Claude Code in this folder and paste it.
4. Check the result yourself: `ffprobe -v error -show_entries stream=width,height,nb_frames:format=duration -of compact launch-video/renders/<product>-launch.mp4` must show 1920x1080, 900 frames, 30 seconds. Look at a few frames (for example `npx --yes hyperframes@0.9.19 snapshot --at 2.5,8,14.5,21,28` inside `launch-video/`) and tell the human what each scene shows.
5. Stop anything left running: the skill often starts a preview server in the background. Run `npx --yes hyperframes@0.9.19 preview --list` inside `launch-video/`, and stop each one with `npx --yes hyperframes@0.9.19 preview <folder> --stop`.

Our numbers (one Mac, November 11, 2026): the build took 8 min 35 s from prompt to finished summary (the render was done at 8 min 23 s), of which the render itself was 1 min 15.5 s by the CLI's own count (900 frames). Their own docs say about 10 to 15 minutes. One follow-up edit ("make the Insights chart fill the left half, Monday drops and turns red") took 2 min 47 s, render 1 min 9.3 s. A 9:16 version as its own project took 4 min 50 s (render 1 min 27.6 s).

Tell the human what they can do next (optional; give them the commands, don't run them unless asked):
- Edit by asking: one short follow-up prompt per change, then re-render to a new file name (`-v2.mp4`) so the first version stays.
- Preview studio: `cd launch-video` then `npx --yes hyperframes@0.9.19 preview` opens http://localhost:3002 with a play button, a timeline and a Variables tab. Changing a value there only previews it; the saved defaults don't change. Ctrl+C to stop.
- Many versions from one template: write `launch-video/rows.json` like `[{"name":"violet","headline":"...","accent":"#7c3aed","promoCode":"..."}, ...]` and run `npx --yes hyperframes@0.9.19 render --batch rows.json --output "renders/batch/{name}.mp4"` inside `launch-video/`. On 0.9.19, do NOT add `--strict-variables` when the rows have a `name` key (see troubleshooting). Ours: 3 versions, 30 s each, about 4 minutes in total.
- Vertical for Shorts: variables can't change the frame size, so ask for a separate project: "Now make a 1080x1920 version for Shorts as its own project in launch-video/vertical: same five scenes and variables, the headline on screen from the first frame, and all text clear of the bottom 20%. Lint, check, and render it to launch-video/vertical/renders/<product>-launch-9x16.mp4."

## Phase 6: Report

Finish with a short report in plain English:
- versions: Claude Code, Node, FFmpeg, HyperFrames (0.9.19)
- telemetry: disabled (quote the status line)
- doctor: which of Node/FFmpeg/FFprobe/Chrome passed, and which optional checks failed
- skills: the four names, and where they were installed
- smoke test: the file path, size, and ffprobe line
- the launch video: the filled prompt, the file path, the ffprobe line, how long the build took, one line per scene, and the variables it exposes
- whether any preview server is still running (it must not be)
- anything that failed and what you did about it

Also write the same report to `hyperframes-kit-report.txt` in the project folder.

---

## Troubleshooting (from what actually happened when we tested)

| What you see | What it means | What to do |
|---|---|---|
| `doctor` ends with "Some checks failed", with ✗ on Docker, Kokoro or MusicGen | Optional extras (cloud-style rendering in Docker, local voice, local music) | Nothing. Only Node, FFmpeg, FFprobe and Chrome matter for rendering. |
| `Telemetry remains disabled because DO_NOT_TRACK is set` | You ran it with `DO_NOT_TRACK=1` in front | Fine. The saved setting is also off now. |
| Claude says `/hyperframes` isn't available | The skills were installed during this session, or Claude Code was started with settings that skip your user folder | Exit and start `claude` again. In our first test the skill wasn't loaded and Claude still made a good card from the CLI's built-in docs (`npx hyperframes@0.9.19 docs`), but with the skill it checks its own frames and fixes more. |
| Auto mode blocks a font download (`curl` to Google Fonts) | Claude Code's safety check is careful with downloads | Approve it if you trust the font source, or let Claude use the Fontsource npm package. Both happened in our tests. |
| The first `lint` fails on an animation (for example letter-spacing that would stutter) | HyperFrames renders frame by frame, so some CSS tricks don't animate the same way | Let Claude fix it; ours swapped it for a scale and blur and lint passed. |
| `lint` suggests upgrading (ours said 0.9.20, with `npx hyperframes@latest upgrade`) | A newer release came out; they ship several a day | Ignore it while you follow this kit. Moving to a newer version is the human's choice, not the agent's. |
| `[hyperframes] .env: ignoring DEMO_SECRET` | The CLI reads a project `.env` for its own settings and prints the NAMES of variables it ignores (never the values) | Nothing. Don't open the `.env` yourself. |
| A preview server is still running after Claude finishes (port 3002 busy) | `preview` keeps running in the background | `lsof -iTCP:3002 -sTCP:LISTEN` shows it; stop it with Ctrl+C in its terminal or `kill <pid>`. |
| Render stops around 5% on a Mac with a security warning | macOS XProtect blocking the downloaded headless Chrome (GitHub issue #6530) | Not seen in our test. Run `npx hyperframes@0.9.19 browser ensure` again, or point `HYPERFRAMES_BROWSER_PATH` at your installed Google Chrome. |
| `FFmpeg not found` at render time | FFmpeg isn't installed or isn't on PATH (issue #5232) | Install it (Phase 0), or set `HYPERFRAMES_FFMPEG_PATH` and `HYPERFRAMES_FFPROBE_PATH` to the binaries. |
| **Added November 11 (the launch-video build):** | | |
| The first video is small text in one corner with lots of empty space | The prompt didn't ask for visuals (our first try, before we added "a real visual that fills the frame") | Name one visual per feature in the prompt, as in Phase 5. |
| A line or logo that should "draw on" just pops in | The SVG used `pathLength="1"` and the dash animation didn't follow it (Claude spotted it in its own test frames) | Let Claude look at frames (`snapshot`); ours switched to real pixel lengths and it drew properly. |
| `check` warns `film_silent` / "This 30 s film has no sound source" | The skill wants music and sound on every film over about 15 s | Fine for a silent video. Say "no music" in the prompt if that's what you want. |
| `check` warns `dead_stretch` ("Nothing on screen changes for 3.63 s") | A scene sits still too long | Let Claude add a move; ours made Monday's bar climb back. |
| Claude starts `preview` by itself and leaves it running | The skill opens the studio before rendering | `npx --yes hyperframes@0.9.19 preview --list`, then `preview <folder> --stop`. |
| A `chrome-headless-shell` keeps running for a few minutes after `check` | `check` keeps a warm browser (`warmCheck.js`, 300000 ms) for the next check | It quits by itself after about 5 minutes. On a low-memory Mac you can stop it: `pkill -f warmCheck.js`. |
| `render --batch rows.json --strict-variables --output "renders/{name}.mp4"` fails: `Variable "name" is not declared in data-composition-variables` then `Aborting batch due to variable issues in row 0, 1, 2 (--strict-variables mode).` | On 0.9.19 the `name` key used for the file name counts as an undeclared variable (the docs page shows the command for the newest version) | Drop `--strict-variables`. The same command without it rendered all 3 rows (`Batch complete: 3 completed.`). |
| The studio's Variables panel labels the variables `unused` | The panel only spots variables bound with `data-var-text` / `var(--name)`; ours were read by script | They still work: changing them in the panel changed the preview and the batch renders. |
| Render output ends with "Keep editing by chatting with Framey in the HyperFrames desktop app" | An ad for HeyGen's desktop app | Optional. Nothing in this kit needs it. |
| `tts` says Python or kokoro-onnx is missing | The local voice needs Python 3.10+ with `kokoro-onnx` and `soundfile` | Only if the human wants a voice: `python3 -m venv .venv-tts && .venv-tts/bin/pip install kokoro-onnx soundfile`, then `export HYPERFRAMES_PYTHON=$PWD/.venv-tts/bin/python`. First `tts` run downloads the model (about 325 MB + 28 MB voices) into `~/.cache/hyperframes/tts`. Ours: install 7 s, first line in 10 s. |

## Sources

- Repo, README and license: https://github.com/heygen-com/hyperframes (Apache-2.0; 80,286 stars and release v0.9.19 per the GitHub API on 2026-11-07)
- Docs and quickstart: https://hyperframes.heygen.com/quickstart
- Telemetry opt-out (`hyperframes telemetry disable`, `DO_NOT_TRACK=1`, `HYPERFRAMES_NO_TELEMETRY=1`): packages/cli/src/commands/telemetry.ts in the v0.9.19 tag
- GSAP license (free, including plugins): https://gsap.com/standard-license
- Our own code review of v0.9.19 before running it (what each command downloads and sends), and our test runs on November 7 and November 11, 2026
- Variables and batch renders: https://hyperframes.heygen.com/concepts/variables
- Kit test (November 11, 2026): a fresh headless Claude Code session given only this file, on a copy of Pulse with a dummy `.env`, its own empty HOME and HyperFrames already in the skills folder: passed in 8 min 33 s (build 5 min 34 s, render 59 s, 1920x1080, 900 frames, 30 s); never opened `.env`, never ran `usage`/`events`, no preview server left running.
- Product launch guide ("about 10 to 15 minutes"): https://hyperframes.heygen.com/guides/product-launch-video
