clawforge: Instructions file for Codex

ClawForge

Demo videos as code — YAML script → Playwright recording → edge-tts narration → ffmpeg → MP4.

Commands

npm test                          # Run all tests (node --test test/*.test.js)
npm start                         # node bin/clawforge.js
npm run example                   # Run examples/demo-script.yaml
clawforge check-deps              # Verify ffmpeg, ffprobe, edge-tts, Playwright
clawforge validate <script.yaml>  # Validate only, no execution
clawforge resume <checkpoint.json># Resume from .clawforge-checkpoints/
clawforge -o <dir>                # Override output directory
clawforge --verbose               # Verbose logging

External deps

• ffmpeg + ffprobe in PATH
• edge-tts Python package (pip install edge-tts)
• Chromium (npx playwright install chromium)

Entrypoints

Purpose	File
CLI	bin/clawforge.js
MCP stdio server	bin/clawforge-mcp.js
MCP SSE server (port 3100)	clawforge-mcp-sse/index.js
Library (npm package)	src/sdk-exports.js → exports ClawForgeSDK

Architecture

ClawForgeSDK (events + checkpoint)
  → ProductionSession.run()
    → 1. narrate()      edge-tts → per-scene MP3s
    → 2. record()       Playwright → single MP4
    → 3. compose()      ffmpeg → final MP4 (concat audio, mix music, burn subtitles/overlay)

MCP tools

• clawforge_produce_video — script path or object, returns {outputPath, stats}
• clawforge_validate_script — validate without running
• clawforge_check_dependencies — status of all deps
• clawforge_dry_run — validate + dep check

Two transports: stdio (npx clawforge-mcp) and SSE (GET /mcp, POST /mcp?sessionId=... on port 3100).

Tests

Uses Node.js built-in test runner. Files: test/smoke.test.js, validator.test.js, errors.test.js, subtitles.test.js, music.test.js, webcam.test.js.

CI (.github/workflows/ci.yml) tests on Node 20.x + 22.x, runs all tests + pipe JSON-RPC through MCP stdio server.