Agentic Video Codex

Starter workspace for reproducing the YouTube workflow analyzed in this repo:

• video-use for transcript-driven cleanup and first-pass editing
• HyperFrames for HTML/CSS/GSAP motion graphics
• Claude Code or ChatGPT Codex as the orchestrator
• local faster-whisper as the default transcription backend on this machine

This is not a traditional software project. It is a production workspace for running repeatable AI-assisted video edits.

What This Workspace Does

The intended flow is:

1. Drop a raw clip into a project folder.
2. Run an edit-only pass with video-use.
3. Approve the cut plan.
4. Generate edited.mp4 and transcript.json.
5. Plan motion graphics beats against exact transcript anchors.
6. Approve the beat plan.
7. Build HyperFrames compositions.
8. Preview, take screenshots, fix issues.
9. Render draft, then final.

Folder Layout

• docs/ Setup and workflow docs.
• external/ Local upstream clones of the core repos used by this workflow.
• prompts/ Copy-paste prompt templates for Claude Code or Codex.
• projects/ One folder per video project.
• scripts/ Small helpers, including project scaffolding.
• style/ Reusable visual and editorial style guides.
• WORKFLOW_SPEC.md Distilled source-of-truth from the three research files.

Quick Start

1. Bootstrap the machine:

make bootstrap AGENT=codex MODEL=large-v3

or:

make bootstrap AGENT=claude MODEL=large-v3

2. Read docs/BOOTSTRAP_NEW_MACHINE.md, docs/SETUP_CLAUDE_CODE.md, or docs/SETUP_CODEX.md.
3. Verify local setup:

make check-setup AGENT=codex

4. Create a new project:

./scripts/new-project.sh my-video

5. Put your raw file in:

projects/YYYY-MM-DD-my-video/raw/raw.mp4

6. Start with:

• prompts/00_BOOTSTRAP_STUDIO.md
• prompts/10_EDIT_ONLY.md
• prompts/20_MOTION_PLAN.md
• prompts/30_BUILD_HYPERFRAMES.md
• prompts/40_REVIEW_AND_FIX.md

Remote Agent Handoff

If you want another machine or another agent to recreate this exact bundle, use:

• docs/BOOTSTRAP_NEW_MACHINE.md
• docs/AGENT_HANDOFF_PROMPT.md

Suggested First Session

For the first run, keep it simple:

• one raw talking-head clip
• one edit-only pass
• four or five motion beats max
• one draft render
• one final render

Do not ask the agent to "make the whole thing awesome" in one shot. Plan first, then build.

Current Status

This repo currently contains:

• the three original research/source files
• a normalized workflow spec
• a reusable starter workspace

The next real milestone is running one full sample project end-to-end.