How to Edit Videos With Claude Code and HyperFrames

You can edit a video with Claude Code or Codex by turning the edit into a deterministic HyperFrames project: give the agent your footage, an explicit edit contract, and a time-coded storyboard; preview and inspect keyframes; then render a repeatable MP4. This workflow is most useful for product demos, talking-head clips, tutorials, and social videos that need captions, overlays, and consistent branding.

The important shift is that the agent is editing a timeline represented in code. You can review every asset, timing decision, and visual rule before rendering, and rerun the same project after a change.

What You Will Build

This guide takes you from raw footage to a reviewed video through this loop:

1. Define the audience, duration, aspect ratio, structure, and acceptance checks.

2. Put footage and approved assets in one project.

3. Turn the brief into a time-coded storyboard.

4. Build the video as a HyperFrames composition.

5. Lint, preview, and inspect representative frames.

6. Render an MP4 and complete a human review.

The expected result is a reproducible video project, not only a one-off exported file.

Prerequisites

You need:

• Claude Code, Codex, or another coding agent with terminal access

• Node.js 22 or newer and npm or Bun available locally

• FFmpeg for local rendering; HyperFrames provides the browser runtime it needs

• Raw footage and assets you have permission to use

• A project folder with enough disk space for source media and rendered output

If you want the agent to find transcription, image, audio, or video-generation Actions through Aident Loadout, give it this exact instruction:

Follow https://aident.ai/SETUP.md

After setup, ask the agent to search the current Aident Loadout catalog and inspect each Action's schema before execution. That lets the agent use the currently available integration rather than depending on a hard-coded provider contract. See how Aident connects Claude Code and Codex to real-world tools and how to keep MCP context usage under control.

Step 1: Write an Edit Contract

Do not start with "make this video better." Give the agent a contract it can test. For example:

Edit media/interview.mp4 into a 45-60 second 1080x1920 video.

Audience: developers evaluating an agent workflow.
Opening: state the problem in the first 3 seconds.
Structure: problem, demonstration, result, CTA.
Captions: burned in, no more than two lines, inside safe margins.
Brand: dark background, white type, one blue accent.
Audio: preserve speech, remove long silence, avoid abrupt cuts.
CTA: show "Try the workflow" for the final 4 seconds.

Acceptance checks:
- No missing media or blank frames.
- Captions match the spoken words and timing.
- Every text overlay remains readable on a phone.
- The final MP4 is 45-60 seconds and 1080x1920.
- Do not render until I approve the preview and keyframes

This contract separates creative choices from objective checks. It also gives the human reviewer clear stopping points.

Step 2: Install and Check HyperFrames

Follow the current HyperFrames quickstart to add the HyperFrames skills to your agent. The documented skill installer command is:

npx skills add heygen-com/hyperframes --all

Then check the local runtime:

npx hyperframes doctor

Resolve reported Chrome, FFmpeg, Node.js, or permission errors before creating the project. A clean diagnostic result prevents many preview and render failures later.

Step 3: Initialize the Project and Add Media

Create a dedicated project with the current non-interactive blank example, then add folders for your inputs and output:

npx hyperframes init product-demo-video --non-interactive --example blank
cd product-demo-video
mkdir -p media output

Copy your approved footage, logos, screenshots, fonts, and audio into media/. Use stable relative paths in the composition. Do not point a hosted Action at a path on your laptop: upload the file through a supported file-storage Action or provide a short-lived download URL when execution happens in a remote sandbox.

For generated or derived assets, ask Aident Loadout to find the current Action before committing to a provider:

Search Aident Loadout for Actions that can transcribe speech, generate a
supporting image, or create a short video insert. Show me the input schema,
pricing metadata, and risk level before executing anything

Keep the original media unchanged. Put generated assets in a separate folder and record the prompt or source for each one.

Step 4: Create a Time-Coded Storyboard

Ask the agent to inspect the footage and propose a storyboard before it writes the composition. A useful first pass looks like this:

Confirm the cut list, words on screen, asset provenance, and total duration. If the source has speech, review the transcript before using it for captions. Automated transcription can misread product names, commands, and acronyms.

Step 5: Build the Composition

Ask the agent to translate the approved storyboard into a named HyperFrames composition. Require it to keep timeline values explicit and derived from the composition clock. HyperFrames emphasizes deterministic rendering, so an identical composition and asset set should produce the same frames each time.

A good build prompt is:

Build the approved vertical composition in HyperFrames.
Use only files under media/ and keep paths relative.
Derive animation state from the composition timeline.
Use components for captions, callouts, and the end card.
Do not add unreviewed claims, stock media, or music.
Stop after linting and starting the preview. Do not render yet

Keep text short enough to read at normal playback speed. Avoid long CSS transitions or animations that depend on wall-clock time because they can become inconsistent when the renderer seeks to an arbitrary frame.

Step 6: Lint, Preview, and Inspect Frames

Run the static checks and list the available compositions:

npx hyperframes lint
npx hyperframes check
npx hyperframes preview

Open the preview and inspect the complete timeline. Check the first frame, every cut, every caption change, the CTA, and the final frame. Also inspect representative stills around transitions with the HyperFrames snapshot or keyframe workflow documented for your installed version.

The preview is ready for approval when:

• all media loads without placeholders or network errors;

• captions match the audio and stay within safe margins;

• cuts occur on the intended words or visual beats;

• animations have a clear beginning and end;

• brand elements and the CTA are readable at mobile size;

• no claim appears that is absent from the approved brief or source material.

Ask a human to approve this checkpoint. Code generation can make the edit faster, but it cannot decide whether a speaker looks awkward at a cut or whether a claim is appropriate for publication.

Step 7: Render and Verify the MP4

After approval, render the selected composition:

npx hyperframes render --output output/final.mp4

If your installed CLI requires a composition name or a Docker flag, use the exact syntax shown by npx hyperframes render --help and the current rendering guide.

Play the exported MP4 from start to finish. Confirm its resolution, duration, audio, caption timing, cuts, and end card. Compare at least the opening, midpoint, and closing frames with the approved preview. Keep the project and source assets alongside the output so a future correction can be made by changing the composition and rendering again.

Common Failures and Fixes

hyperframes doctor reports missing dependencies

Fix every failed diagnostic before debugging the composition. Verify that Chrome or Chromium and FFmpeg are executable from the same shell that runs HyperFrames. In a container, follow the documented Docker rendering path.

The preview shows missing media

Use project-relative paths and verify the filename's case. Do not rely on an authenticated browser URL or a temporary link that expires during render. Download remote assets into the project before the build when licensing and the Action contract allow it.

Animation looks different after seeking or rendering

Derive animation from timeline time instead of Date.now(), timers, or mutable state. HyperFrames' determinism guide explains why every frame must be reproducible at any seek position.

Captions drift away from speech

Check whether transcript timestamps are segment-level or word-level, then map them to the composition time base once. Review product names manually and split long caption blocks before adjusting visual timing.

A short clip stops before the scene ends

Either shorten the scene, choose a longer source, or define an intentional loop that covers the scene. Upgrade to a current HyperFrames release and review the changelog when a valid loop is rejected; v0.7.68 included a fix for short looping video coverage checks.

Nested styles or complex scenes fail validation

Reduce the scene to the smallest failing component, run npx hyperframes lint --verbose, and compare your installed version with the HyperFrames changelog. Version-specific parser and renderer fixes are easier to identify before changing the creative design.

Rendering is slow or runs out of memory

Reduce source resolution when the final format does not need it, remove unused assets, and test a draft before the full render. Run npx hyperframes benchmark to find an appropriate worker count for the machine.

Why This Workflow Works

Traditional video editors store decisions inside a project UI. An agent can operate that UI, but the result is difficult to inspect as a contract. HyperFrames represents the composition in HTML, CSS, and JavaScript and renders it against a deterministic timeline. The agent can therefore propose an edit, the human can review the plan and preview, and automated checks can catch missing assets or invalid structure before the expensive render.

The reusable pattern is simple: explicit brief, stable assets, time-coded storyboard, deterministic build, visual checkpoints, and human approval. It gives Claude Code or Codex enough structure to help with real editing work without treating the first generated result as final.

Connect the Rest of the Media Workflow

Use Aident Loadout to let your agent discover current transcription, image, audio, and video Actions, inspect their schemas, and keep the connection setup separate from the edit itself. For your first test, take one 30-60 second source clip through the full contract, preview, render, and review loop, then record whether the final MP4 passed every acceptance check without manual timeline repair.

Sources

• HyperFrames quickstart

• HyperFrames production pipeline

• HyperFrames rendering guide

• HyperFrames determinism guide

• HyperFrames performance guide

• HyperFrames troubleshooting guide

• HyperFrames common mistakes

• HyperFrames GitHub repository

Refresh this guide when HyperFrames changes its installation, project structure, lint, preview, snapshot, or render commands, or when Aident Loadout's recommended media Actions change.