Jonathon's AI Wiki

HeyGen Studio CLAUDE.md Template (Bootstrap Pattern)

5 min read

Source: raw/heygen-studio-template/CLAUDE.md

HeyGen ships a CLAUDE.md inside its course-video pipeline template so any developer who clones the repo gets Claude Code instantly briefed on the project’s three-stage architecture (load script → ElevenLabs TTS → HeyGen avatar video) and the operator commands that drive it. It is a small but load-bearing artifact: the template assumes Claude Code is the orchestrator rather than a hand-holding pair-programmer, so the CLAUDE.md doubles as the project’s primary README and the agent’s system prompt.

Key Takeaways

  • Three-stage pipeline, one Python file. generate_videos.py runs every lesson chunk through six sequential steps — load script, sentence-boundary split, ElevenLabs TTS, upload to HeyGen, create video, poll-and-download — and state.json tracks every step so a re-run skips completed work and resumes mid-pipeline.
  • Resumable by design. Failed step does not lose prior work; the operator fixes the cause and re-runs python generate_videos.py. State management is the architectural primitive the rest of the template hangs off.
  • Dual script source. Scripts can come from local .txt files in scripts/ or from Google Docs via the gws CLI — the lesson config switches with "source": "local" vs "source": "google_doc".
  • .env carries secrets, config.json carries identity. API keys (HEYGEN_API_KEY, ElevenLabs key) live in .env; avatar ID, voice ID, voice settings, chunk size, concurrency, and the full lesson manifest live in config.json.
  • Dry-run before paid runs. python generate_videos.py --dry-run exports and splits scripts with zero API calls, so chunk boundaries can be inspected before any HeyGen or ElevenLabs credit is spent.
  • Explicit “Using Claude Code With This Project” section. The CLAUDE.md enumerates concrete asks the agent is expected to handle — “add lessons 2.0 through 2.5 to my config”, “my lesson 1.0 failed at audio generation — help me debug it”, “change the chunk size to 150 words”. This is the prompt-shape contract between operator and agent.
  • Two supplementary scripts for HeyGen motion-engine upgrades. heygen_update.py (Playwright browser automation) re-renders existing videos against a new HeyGen motion engine; redownload_videos.py pulls the re-rendered MP4s. Only needed during engine-version transitions.
  • Concurrency-limited batches. Default 3 concurrent video requests respect HeyGen’s API rate limits; audio generation and upload happen in parallel within each batch.
  • Bootstrap pattern, not a “vibe coding” pattern. The CLAUDE.md ships authoritative architecture documentation — six-stage pipeline, state-management contract, config schema, troubleshooting matrix — so an agent picking up the project mid-flight does not need to infer structure from code.

Why the Template Matters

  • HeyGen treats CLAUDE.md as a first-class project artifact. Most templates lead with README.md and add CLAUDE.md as an afterthought; this one collapses the two — the same file briefs a human and a coding agent.
  • The template’s surface area is small enough to read at session start. ~195 lines. Quick Start (6 numbered steps), Commands table, Architecture (state + concurrency), Configuration table, Supplementary Scripts, Using Claude Code (worked example prompts), Output Structure, Troubleshooting (five canonical errors with cause + fix). The agent can hold the whole project in its head.
  • The “things you can ask” enumeration is the load-bearing pattern. Telling the agent what shape of request to accept (“add lessons 2.0 through 2.5”, “debug lesson 1.0 audio generation”) narrows the prompt space and reduces underspecified asks. Worth lifting into any project where Claude Code is the orchestrator.

Implementation

Tool/Service: HeyGen Studio template project (Python; ships with companion generate_videos.py + config.json + state.json schema; bundled with the larger HeyGen + Claude Code walkthrough — see HeyGen Studio Automation with Claude Code).

Setup (operator workflow):

  1. Clone the template, then:

    pip install -r requirements.txt
cp .env.example .env

  2. Edit .env to add real HeyGen + ElevenLabs API keys.

  3. Edit config.json:

    • Paste your HeyGen avatar ID (from app.heygen.com → Avatars → click the avatar → URL).
    • Paste your ElevenLabs voice ID (from elevenlabs.io → Voices → click voice → settings panel).
    • Add lesson entries under lessons with "source": "local" and a file path, or "source": "google_doc" and a doc_id.

  4. Verify with a dry run (no API spend):

    python generate_videos.py --dry-run

  5. Smoke-test with one lesson and one chunk before processing the full course:

    python generate_videos.py --lesson 1.0 --max-parts 1

  6. Full pipeline: python generate_videos.py. Resume after failure: re-run the same command — state.json keeps every completed step.

Cost:

  • Template itself: free (open source, ships from HeyGen). ^[inferred — license not stated in CLAUDE.md]
  • HeyGen + ElevenLabs API charges: per-call against the user’s accounts.

Integration notes:

  • The gws CLI is only required if any lesson uses "source": "google_doc". Local .txt scripts work without it.
  • Audio duration warning fires above 65 seconds per chunk — lower max_chunk_words in config.json if it triggers.
  • heygen_update.py requires pip install playwright && playwright install chromium; only run during a HeyGen motion-engine version upgrade.
  • The state-tracked-resumable pattern is reusable beyond this template: any multi-stage agent-driven pipeline benefits from a state.json checkpoint so partial failures do not redo paid work.

Try It

  1. Clone the template, run python generate_videos.py --dry-run against a sample script, and confirm the sentence-boundary split produces chunks at or under your max_chunk_words.
  2. Read the CLAUDE.md “Using Claude Code With This Project” section, then in a fresh Claude Code session in the project directory, try one of the listed prompts verbatim (e.g., “Add lessons 2.0 through 2.5 to my config”) and observe how the agent uses the template’s structure to route the change.
  3. Adopt the pattern for an unrelated multi-stage pipeline you own: write a one-page CLAUDE.md with project overview, quick-start (numbered steps), commands table, architecture (state contract), and an explicit “things you can ask” section. Measure whether prompt latency or hand-holding drops on the next agent session.
  4. If you already run HeyGen Studio Automation with Claude Code, compare your project’s CLAUDE.md to this template’s structure — the template version’s troubleshooting matrix and explicit prompt examples are the easiest wins to backport.

Graph View

Backlinks