video-essay

video-essay

A Claude Code plugin for making video essays. Three short-form videos enter, one wins at 24 hours, becomes a 10-minute long-form. Research → TTS → image gen → caption burn-in → multi-platform publish → retention-aware judging.

Install

/plugin marketplace add robertnowell/video-essay
/plugin install video-essay@video-essay-marketplace

At install, Claude prompts for 7 config values — the paths + API keys the pipeline needs. All sensitive fields are stored in the OS keychain (via plugin userConfig), not in plaintext on disk. The SessionStart hook bridges them to the env var names the scripts read.

Requirements

• Python 3.12+ (brew install [email protected])
• ffmpeg + ffprobe (brew install ffmpeg)
• Google Chrome or Chromium (headless HTML→PNG rendering)
• API keys from: ZapCap, ElevenLabs, Gemini, Upload-Post, optionally OpenAI
• For YouTube publishing (optional): a Google Cloud project with YouTube Data API v3 + YouTube Analytics API enabled, and an OAuth 2.0 Desktop-app client (yields GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET). First publish triggers browser OAuth; token is cached thereafter.

See references/env_setup.md for the per-key reference.

Preflight

Before any paid work:

ve-doctor --live

Checks every env var + binary + OAuth token, validates each API key against its vendor endpoint. Exits 0 when everything's ready.

The stages

Invoke	Stage	Covers
/video-essay <topic>	dispatcher	Routes based on episode state
/ve-intake	0–3	Preflight, topic intake, angles research, pick 3 angles
/ve-produce	4–5	Per-angle hook research, script → judge → audio → images → covers → captioned video
/ve-publish-shorts	6–7	Bible-compliance visual gate, then publish to YouTube Shorts + IG Reels + TikTok (staggered)
/ve-analyze	8–9	24h metrics pull, viral scoring, winner decision
/ve-longform	10	Title + thumbnail lock, deep research, script, audio, images, assemble, publish long-form

The algorithm picks the winning short at 24h — no LLM judgment. The LLM judges only enforce Bible compliance pre-publish. See references/shorts_bible.md for the canonical short-form rules and references/shorts_script_judge_rubric.md for the two-phase script judge.

Architecture

• skills/ — 5 stage-aligned sub-skills + 1 dispatcher. Each is a focused SKILL.md that Claude Code auto-routes to based on episode state.
• pipeline/ — Python scripts that do the deterministic work (TTS, ffmpeg, API uploads). Installed as an importable package via pyproject.toml.
• hooks/ + hooks-handlers/ — SessionStart hook: Python check, hash-gated venv install, credential bridge from CLAUDE_PLUGIN_OPTION_* to clean env var names.
• bin/ — 9 ve-* shell wrappers on $PATH (ve-doctor, ve-audio, ve-images, ve-thumbnail, ve-assemble, ve-qa-images, ve-publish-shorts, ve-analyze-shorts, ve-publish-youtube).
• references/ — Canonical rules: Shorts Bible, judge rubrics, style guide, vendored deep-research skill, reference script examples (Wendover, PolyMatter, Tom Scott).

Testing

bash tests/integration.sh

26-check regression suite: plugin manifest validation, SessionStart hook behavior, path resolution, YouTube token cascade, Phase A regression (hard-fail on missing captions key, re-run idempotency). First run ~45s (builds test venv); re-runs ~5s.

License

MIT.