Skip to main content
skill CX Codex

hyperframes-cli · coco-research — Claude Code skill for video rendering

The hyperframes-cli skill guides HyperFrames projects from composition checks to preview and rendering. It also helps diagnose build and render failures.

MIT ★ 328 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add coco-research/coco --skill hyperframes-cli -a claude-code
Open on GitHub

What hyperframes-cli does

The skill lays out a HyperFrames workflow: scaffold a project, run npx hyperframes lint during edits, then use npx hyperframes check as the final gate. That check opens a browser to inspect runtime errors, failed requests, layout issues, and contrast. Once it passes, open the composition preview and verify the rendered file.

Rendering options include local and batch jobs, HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run. For agent and CI calls, the skill recommends --json; server-mode render, preview, and play do not return ordinary JSON. Wait for approval of the final preview before rendering.

The CLI requires Node.js 22 or newer and FFmpeg. Install the skill in Claude Code with the command below. Unless project instructions supply a wrapper, run CLI commands through npx hyperframes.

What it helps with

  • scaffold a HyperFrames project
  • check a composition for browser and layout issues
  • compare composition snapshots after edits
  • render video locally or through a cloud service
  • verify the rendered file and its duration

Example prompts for the agent

  • Set up a HyperFrames project called promo and guide me through its development loop.
  • Run npx hyperframes check on the composition, then open its preview.
  • After I approve the preview, render to out.mp4 at high quality and verify the file.

How to install hyperframes-cli

1Skills CLI (Vercel)

npx skills add coco-research/coco --skill hyperframes-cli -a claude-code

2Manually: put the files in place

~/.claude/skills/hyperframes-cli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/hyperframes-cli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about hyperframes-cli

How do I install hyperframes-cli in Claude Code?

Run npx skills add coco-research/coco --skill hyperframes-cli -a claude-code. The skill file will be at ~/.claude/skills/hyperframes-cli/SKILL.md.

What does hyperframes-cli do?

It guides the HyperFrames CLI workflow from project setup and checks through preview and rendering. It also covers diagnosing build and render failures.

What does hyperframes-cli require?

It requires Node.js 22 or newer and FFmpeg. Use npx hyperframes to run commands unless the project provides a wrapper.

Source text

SKILL.md · MIT
---
name: hyperframes-cli
description: >
  Use the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot,
  compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish,
  cloud, cloudrun, feedback, lambda, doctor, browser, info, upgrade, skills, compositions, docs,
  benchmark, telemetry, transcribe, auth, tts, and remove-background. Also use when diagnosing build
  or render failures. validate, inspect, and layout are deprecated aliases; use check. Covers local,
  HeyGen-hosted cloud, AWS Lambda, and Google Cloud Run rendering.
---

# HyperFrames CLI

Run commands as `npx hyperframes ...` unless project instructions provide a wrapper. Obey the wrapper when present. The CLI requires Node.js 22 or newer and FFmpeg.

## Development loop

1. **Scaffold:** `npx hyperframes init <project>` or capture a site. In non-TTY mode, pass `--non-interactive --example=<name>`.
2. **Author:** write the composition using `/hyperframes-core`.
3. **Get fast feedback while editing:** run `npx hyperframes lint` after the first HTML pass and after structural changes.
4. **Run the final gate:** run `npx hyperframes check`; it reruns lint before opening the browser. Do not prepend a redundant standalone lint invocation. Add `--snapshots` for annotated overview frames and finding crops.
5. **Inspect sub-compositions:** when `index.html` mounts `data-composition-src`, capture midpoint snapshots and inspect each mounted scene.
6. **Open the final Studio preview:** run `npx hyperframes preview`, hand the timeline project URL to the user, and ask whether to revise or render.
7. **Render only after approval:** use draft quality for iteration and high quality for delivery.
8. **Verify the output:** confirm the file exists, is non-empty, and has a plausible duration.

```bash
# Fast iteration check; repeat while authoring as needed.
npx hyperframes lint

# Required final gate; includes lint.
npx hyperframes check
npx hyperframes preview
npx hyperframes render --quality high --output out.mp4
test -s out.mp4
ffprobe -v error -show_format out.mp4
```

`check` runs lint first, then uses one browser session and one seek pass to audit runtime errors, failed requests, layout, `*.motion.json` assertions, and WCAG contrast. Persistent findings gate the exit code; transient entrance or exit findings are informational. Use `--strict` to gate warnings. `validate`, `inspect`, and `layout` remain aliases for compatibility but must not appear in new instructions or scripts.

## Two different preview surfaces

Do not confuse these states:

| Surface                   | When it may open                                       | Purpose                                                                           |
| ------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------- |
| Storyboard board          | Before composition checks, only when `storyboard: yes` | Review plan cards and wireframe sketches. Open `?view=storyboard#project/<name>`. |
| Final composition preview | After `check` passes                                   | Review the assembled timeline before render. Open `#project/<name>`.              |

The early board is not approval of the final video. Rendering always requires the final approval defined by `hyperframes-core/references/review-loop.md`.

## Sub-composition smoke test

Static audits cannot catch every mount failure. When the project uses sub-compositions, capture at least one visible midpoint for each host slot:

```bash
npx hyperframes snapshot --at <t1>,<t2>,<t3>
```

Treat tiny unstyled content, canvas-sized icons, missing hero elements, or timeline-registration timeouts as render-blocking mount defects. See `hyperframes-core/references/sub-compositions.md` for the corresponding fixes.

## Agent conventions

- Prefer `--json` for agent and CI calls. Server-mode `render`, `preview`, and `play` do not provide ordinary JSON output; `preview --selection --json` and `preview --context --json` are query-mode exceptions.
- `doctor --json` always exits zero. Gate on its payload:

  ```bash
  npx hyperframes doctor --json | jq -e '.ok' >/dev/null
  ```

- Non-TTY mode is automatic. `init` requires `--example` there; use `--non-interactive` to force deterministic behavior on a TTY.
- Use one `HYPERFRAMES_RUN_ID` for all commands in the same verification loop.
- Use `--strict`, `--strict-all`, and `--strict-variables` when the corresponding warnings, variables, or CI conditions must gate the render.
- JSON paths redact the home directory as `$HOME`; do not try to reverse the redaction.
- When a hosted cloud project approaches or exceeds the 200 MB upload limit, use `cloud render --dry-run --json` and follow the `.hyperframesignore` investigation in `references/cloud.md`. Never ignore an asset merely because it is large.
- Never render merely because checks pass. Pause at the final preview and wait for approval.

## Studio-directed edits

When the user refers to “this element” or the current selection, query Studio instead of guessing:

```bash
npx hyperframes preview --context --json --context-fields selection
```

Use `selection.target.hfId` when available, otherwise its selector and source file. If the result reports `no-selection`, ask the user to click the element and rerun. Request only the context slices you need; use `--context-detail full` only for computed styles or editable text metadata. Full behavior and failure codes live in `references/preview-render.md`.

## Render choices

| Need                                     | Command                                                                       |
| ---------------------------------------- | ----------------------------------------------------------------------------- |
| Fast local iteration                     | `npx hyperframes render --quality draft`                                      |
| Final local delivery                     | `npx hyperframes render --quality high --output out.mp4`                      |
| Reproducible container render            | `npx hyperframes render --docker --strict --output out.mp4`                   |
| Local variable-driven batch render       | `npx hyperframes render --batch rows.json --output "renders/{name}.mp4"`      |
| HeyGen-hosted zero-infrastructure render | `npx hyperframes cloud render`                                                |
| Self-managed distributed AWS render      | `npx hyperframes lambda render <project> --width 1920 --height 1080 --wait`   |
| Self-managed distributed GCP render      | `npx hyperframes cloudrun render <project> --width 1920 --height 1080 --wait` |

Skill attribution is automatic — the examples above need no `--skill`. A project scaffolded by a workflow (`hyperframes init --skill=<workflow>`) records its owning skill in `hyperframes.json`, and every later render inherits it on anonymous telemetry: re-renders, `npm run render`, and `--batch` alike. Pass `--skill=<slug>` explicitly only to stamp a project that was not created through a workflow (its first render then persists it).

Use cloud rendering when the user wants hosted rendering without local Chrome, FFmpeg, or AWS. Use Lambda only when AWS ownership is a requirement. Use Cloud Run only when GCP ownership is a requirement. Read the matching reference before running any cloud path.

After verifying a successful render, send one feedback report unless telemetry is disabled or the user opted out:

```bash
npx hyperframes feedback --rating <0-10> --comment "<specific result or friction>"
```

Keep clean-run feedback concise. For any bug or friction, capture a **reproduction packet** before submitting; do not send only a symptom summary. Include the rerunnable command (relative to the project directory — feedback is submitted to a public channel, so do **not** paste absolute paths, home-directory prefixes, or user/machine identifiers), expected versus actual behavior, exact error (also strip absolute paths from stack traces — keep basename + line, drop the leading directory), whether output completed/fell back/failed, workaround, and repro-project status. For a rating ≤ 7 that describes a visual defect (black frame, flicker, corrupt output, wrong frame, blank output, other visual anomaly), also include a `COMPOSITION_STRUCTURE:` block — a privacy-preserving structural anatomy (element census + attribute presence + timeline shape) so maintainers can pattern-match against known bug families without the composition ZIP. Agents auto-fill this via the composition-census helper; the human user does not fill it by hand. If the issue did not reproduce again, say so and still include the last failing command and logs. Use `--file-issue` only with consent: it publishes a minimal reproduction to a public URL. The required packet format and privacy warning live in `references/preview-render.md`.

## Read the matching reference before running a command

The following references and owning skills are mandatory command contracts, not optional background reading. Before running a command in the table, read its matching row.

| Need                                                                                   | Reference                             |
| -------------------------------------------------------------------------------------- | ------------------------------------- |
| `init`, `capture`, `skills`                                                            | `references/init-and-scaffold.md`     |
| `lint`, `check`, motion sidecars, `snapshot`                                           | `references/lint-validate-inspect.md` |
| `compare`, `grade-compare`, variable-driven `render --batch`                           | `references/compare-and-batch.md`     |
| `beats` for an existing project's Studio beat grid                                     | `references/beats.md`                 |
| `preview`, `play`, `render`, `publish`, Studio context, feedback                       | `references/preview-render.md`        |
| `doctor`, browser management                                                           | `references/doctor-browser.md`        |
| `auth`, HeyGen-hosted cloud rendering, and template variables                          | `references/cloud.md`                 |
| AWS Lambda deployment and rendering                                                    | `references/lambda.md`                |
| Google Cloud Run deployment and rendering                                              | `references/cloudrun.md`              |
| `info`, `upgrade`, `compositions`, `docs`, `benchmark`, telemetry, media preprocessing | `references/upgrade-info-misc.md`     |

For composition variables, also read `/hyperframes-core` → `references/variables-and-media.md`. For `hyperframes add` and `hyperframes catalog`, use `/hyperframes-registry`. Before `hyperframes present`, read `/slideshow`; before `hyperframes keyframes`, read `/hyperframes-keyframes`. For TTS, transcription, captions, or background removal choices, use `/media-use`.

The specialized commands are deliberately documented by their owning workflows:

```bash
npx hyperframes present <project-dir> --port 3004 --no-open
npx hyperframes beats <project-dir> --json
npx hyperframes keyframes <project-dir> --json
```

`present` serves a navigable deck with presenter and audience synchronization. `beats` is the standalone Studio beat-grid utility defined in `references/beats.md`. `keyframes` surfaces seek-safe animation and motion-path diagnostics.

© coco-research · MIT · coco-research/coco

Similar skills

All skills for Frontend and UI →

hyperframes-cli by other authors comes first.

hyperframes-cli heygen-com hyperframes-cli is a Claude Code skill for managing HyperFrames video projects, from scaffolding and frame checks to timeline edits and rendering. The agent invokes it to inspect or build a video. CX Codex +1 1,700,000installs hyperframes-cli boraoztunc hyperframes-cli controls the HyperFrames video pipeline through npx hyperframes, covering scaffolding, layout verification, studio preview, and final rendering. CX Codex +1 216installs hyperframes-cli calesthio hyperframes-cli guides the HyperFrames video build loop, from composition validation and timeline inspection to AWS Lambda rendering. CX Codex +1 ★ 78,316repo stars hyperframes heygen-com hyperframes — a Claude Code skill that renders video from HTML by seeking a paused timeline frame by frame. CX Codex +1 1,600,000installs remotion-to-hyperframes heygen-com remotion-to-hyperframes ports video code from Remotion, Motion Canvas, Lottie, or 3D renders into HyperFrames. Runs automated frame-by-frame diffs against the original video file to catch visual drifts. CX Codex +1 651,200installs hyperframes-video-composition calesthio hyperframes-video-composition is a Claude Code skill that orchestrates HTML, CSS, and JS video assembly with HyperFrames. It guides composition briefs, frame specifications, scene timing, and QA. CX Codex +1 161installs hyperframes-registry official HeyGen hyperframes-registry helps install and wire registry blocks and components into HyperFrames video compositions. CX Codex GP ChatGPT +1 2installs hyperframes-ad-director OneWave-AI hyperframes-ad-director turns a marketing brief into a finished short-form video ad built in HyperFrames: hook, script, storyboard, HTML composition, captions, and voiceover. CX Codex +1 185installs hyperframes-sales-demo-builder OneWave-AI hyperframes-sales-demo-builder — a skill for Claude Code, Codex, Cursor and other platforms that builds a prospect-specific demo video in HyperFrames. CX Codex +1 157installs

From the same set82

The whole set →
toolkit The toolkit command maps project tasks to tools and skills, noting the best option, a fallback and when to skip it; it runs inside /team runs. CX Codex +1 ★ 328repo stars arch-index Builds a validated map of repository components in .arch/index.json and checks it for drift against the code. Use it to trace a component to its files or review structural changes after a refactor. CX Codex +1 ★ 328repo stars hyperframes-keyframes hyperframes-keyframes keeps HyperFrames motion seekable: builds keyframes for GSAP, CSS, Anime.js and WAAPI, then verifies frames before a render. CX Codex +1 ★ 328repo stars pmstudio-meeting-notes pmstudio-meeting-notes converts call transcripts into structured Markdown meeting notes. Cross-references people against stakeholder tables, logs decisions, and flags PRD updates. CX Codex +1 ★ 328repo stars _index _index — a Claude slash command that reads, searches and triages Outlook mail through subcommands such as unread, summary and triage. CX Codex +1 ★ 328repo stars brain:wiki brain:wiki is a Claude Code skill that searches, generates, and merges articles about people, systems, and teams from a distributed knowledge graph. CX Codex +1 ★ 328repo stars hyperframes Entry point for building video, animation and motion graphics in Claude, taking a brief or a URL through to a finished HyperFrames composition. CX Codex +1 ★ 328repo stars code-verification code-verification runs a mechanical 7-category audit on code changes. Catches temporal dead zone bugs, import mismatches, dead code, and React state mistakes. CX Codex +1 ★ 328repo stars

Project sponsors

Companies that keep this analytics open