videoclaw logo # videoclaw **Turn a one-line idea into a finished AI video — step by step, in the open, with a human approval before anything expensive runs and automated QC before anything ships.** A command-line tool (`vclaw`) that takes a plain-English idea like *"a 15-second ad for my coffee brand"* and walks it all the way to a reviewed, published video — using AI video services like **Veo, Seedance, and Runway**. Every step is saved to a file you can read, so nothing is hidden and you can stop, inspect, or replay any stage. Optional vision QC can inspect motion defects such as breath vapour, morphing, vanishing props and character drift. It requires a configured vision backend; final playback review remains separate. [![CI](https://github.com/davendra/videoclaw-v3/actions/workflows/ci.yml/badge.svg)](https://github.com/davendra/videoclaw-v3/actions/workflows/ci.yml) [![Node](https://img.shields.io/badge/node-20%2B-brightgreen)](./package.json) [![TypeScript](https://img.shields.io/badge/typescript-strict%20%7C%20NodeNext%20ESM-3178c6)](./tsconfig.json) [![Status](https://img.shields.io/badge/status-active%20development-orange)](https://videoclaw-docs.vercel.app/reference/MASTER_PLAN_ALIGNMENT) [![License](https://img.shields.io/badge/license-source--available%20%7C%20commercial%20paid-blue)](./LICENSE) [What is it?](#-what-is-videoclaw-in-plain-english) · [What you can do](#-what-you-can-do-with-it) · [How it works](#-how-it-works-step-by-step) · [The main parts](#-the-main-parts-explained-simply) · [Quickstart](#-quickstart) · [Deep docs](#-documentation-map) ### 📚 Full documentation site → **[videoclaw-docs.vercel.app](https://videoclaw-docs.vercel.app/)** The complete, idiot-proof **and** agent-ready docs: an [interactive guide](https://videoclaw-docs.vercel.app/guide/), a page for [**every feature**](https://videoclaw-docs.vercel.app/features/) (30+), a [recipe book](https://videoclaw-docs.vercel.app/guide/what-videos) of what you can make, the [skills catalog](https://videoclaw-docs.vercel.app/skills/), and all the deep [reference docs](https://videoclaw-docs.vercel.app/reference/) — with diagrams throughout. > **New here?** The easiest path is to **[drive it by talking to Claude Code](https://videoclaw-docs.vercel.app/guide/with-claude-code)** (or any agent host); there's a dedicated [how-it-works page for agents](https://videoclaw-docs.vercel.app/for-agents/) too. > > **Agents working in this repo:** read [`docs/CAPABILITIES.md`](docs/CAPABILITIES.md) (or [`llms.txt`](llms.txt)) — a one-read capability manifest: what videoclaw can produce, the provider routes, the spend-safety model, and a command map that names every registered command (exact flags: `vclaw schema --json` and `docs/CLI_REFERENCE.md`). Run `vclaw schema --json` for exact flags. > Once you're in Claude Code in this repo, just type **`/concierge`** (or **`/videoclaw`**) — or say *"make me a video"* — and **VideoClaw**, speaking as its own concierge, walks you from idea to finished film, with a preview and your approval before anything costs money. videoclaw documentation site — make AI videos by just talking
--- ## 🗺️ Explore the docs Everything lives at **[videoclaw-docs.vercel.app](https://videoclaw-docs.vercel.app/)** (there's a search box on every page). **Guide** — [Start here](https://videoclaw-docs.vercel.app/guide/) · [Use it with Claude Code](https://videoclaw-docs.vercel.app/guide/with-claude-code) · [Install & setup](https://videoclaw-docs.vercel.app/guide/install) · [Your first video](https://videoclaw-docs.vercel.app/guide/first-video) · [What videos can you make?](https://videoclaw-docs.vercel.app/guide/what-videos) · [How it works](https://videoclaw-docs.vercel.app/guide/concepts) · [Storyboard vs Director](https://videoclaw-docs.vercel.app/guide/modes) · [Characters](https://videoclaw-docs.vercel.app/guide/characters) · [Providers](https://videoclaw-docs.vercel.app/guide/providers) · [Review & publish](https://videoclaw-docs.vercel.app/guide/review-publish) · [Assemble & polish](https://videoclaw-docs.vercel.app/guide/assemble) · [Troubleshooting](https://videoclaw-docs.vercel.app/guide/troubleshooting) · [Cheat sheet](https://videoclaw-docs.vercel.app/guide/cheatsheet) **Skills & tools** — [Skills catalog](https://videoclaw-docs.vercel.app/skills/) · [Video skills](https://videoclaw-docs.vercel.app/skills/video) · [Workflow skills](https://videoclaw-docs.vercel.app/skills/workflow) · [Scripts & tooling](https://videoclaw-docs.vercel.app/tooling/) · [For agents](https://videoclaw-docs.vercel.app/for-agents/) **Reference** — [Reference home](https://videoclaw-docs.vercel.app/reference/) · [Architecture](https://videoclaw-docs.vercel.app/reference/ARCHITECTURE) · [CLI reference](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE) · [Production workflow](https://videoclaw-docs.vercel.app/reference/PRODUCTION_WORKFLOW) · [Provider platform](https://videoclaw-docs.vercel.app/reference/PROVIDER_PLATFORM) · [Story bible](https://videoclaw-docs.vercel.app/reference/STORY_BIBLE) · [Assemble](https://videoclaw-docs.vercel.app/reference/ASSEMBLE) · [Internal plans & specs](https://videoclaw-docs.vercel.app/reference/internal/)
Features — a page for every feature (click to expand all 31) [All features](https://videoclaw-docs.vercel.app/features/) - **Create** — [projects & lifecycle](https://videoclaw-docs.vercel.app/features/projects-lifecycle) · [one-shot create](https://videoclaw-docs.vercel.app/features/one-shot-create) · [briefs](https://videoclaw-docs.vercel.app/features/brief) · [brand DNA](https://videoclaw-docs.vercel.app/features/brand-dna) · [storyboards](https://videoclaw-docs.vercel.app/features/storyboard) · [storyboard grid](https://videoclaw-docs.vercel.app/features/storyboard-grid) · [story bible](https://videoclaw-docs.vercel.app/features/story-bible) - **Direct & refine** — [director mode](https://videoclaw-docs.vercel.app/features/director-mode) · [prompt quality](https://videoclaw-docs.vercel.app/features/prompt-quality) · [multi-shot](https://videoclaw-docs.vercel.app/features/multi-shot) · [filmmaking & cinematography](https://videoclaw-docs.vercel.app/features/filmmaking-prompts) - **Keep it consistent** — [characters](https://videoclaw-docs.vercel.app/features/characters) · [reference sheets](https://videoclaw-docs.vercel.app/features/reference-sheets) · [scene candidates](https://videoclaw-docs.vercel.app/features/scene-candidates) · [Seedance Asset Library](https://videoclaw-docs.vercel.app/features/seedance-assets) - **Generate** — [providers & routing](https://videoclaw-docs.vercel.app/features/providers) · [execution runtime](https://videoclaw-docs.vercel.app/features/execution) · [overnight batch queue](https://videoclaw-docs.vercel.app/features/batch-queue) - **Finish** — [assembly](https://videoclaw-docs.vercel.app/features/assemble) · [review UI](https://videoclaw-docs.vercel.app/features/review-ui) · [preview portal](https://videoclaw-docs.vercel.app/features/preview-portal) · [publishing](https://videoclaw-docs.vercel.app/features/publish) - **Manage** — [templates & cloning](https://videoclaw-docs.vercel.app/features/templates-cloning) · [portfolio & ops](https://videoclaw-docs.vercel.app/features/portfolio-ops) · [doctor](https://videoclaw-docs.vercel.app/features/doctor) · [Obsidian](https://videoclaw-docs.vercel.app/features/obsidian) · [telemetry & cost](https://videoclaw-docs.vercel.app/features/telemetry-cost) - **Plan & agents** — [studio planner](https://videoclaw-docs.vercel.app/features/studio) · [agent surface](https://videoclaw-docs.vercel.app/features/agent-surface) · [Veo CLI](https://videoclaw-docs.vercel.app/features/veo-cli)
--- ## 🎯 What is videoclaw? (in plain English) videoclaw is a tool you run in your terminal that **makes AI videos for you, one careful step at a time.** You give it an idea. It writes a short brief, plans the shots (a *storyboard*), generates the video clips with an AI provider, stitches them together with narration and music, lets a human approve the result, and marks it published. That's it. **Think of it like an assembly line for video.** Your idea goes in one end; a finished MP4 comes out the other. At each station along the line, the machine writes down exactly what it did in a file you can open and read. If something looks wrong, you can rewind to any station and try again — you never have to start over from scratch. Three things make it different from the usual *"type a prompt, get a video"* tools: - **It never hides what it's doing.** Every stage leaves a plain, readable file behind. And if a video provider fails, it tells you loudly — it does **not** quietly swap in a different provider and pretend it worked. - **It has a "stop and check" button.** In *director mode* it refuses to spend money on the real render until a human has looked at the storyboard and said "yes, go." - **It supports review before you ship.** Vision QC can inspect rendered clips for motion defects and character drift. It needs a configured vision backend and does not replace inspecting the final output and recording review evidence. > **New here?** You don't need to understand any of the technical sections lower down. Read the next four short sections and you'll know what this whole thing does. ### Who is it for? - **Creators & marketers** who want repeatable, reviewable AI videos — product ads, presenter explainers, UGC campaigns, music videos. - **Small teams** juggling many video projects who need a single dashboard of what's stuck, what needs a look, and what's ready to ship. - **AI agents** — everything is machine-readable, so an automated agent can drive the whole pipeline on its own. --- ## ✨ What you can do with it - **Go from idea → finished video** without leaving the terminal. - **Use several AI video engines** (Veo, Seedance, Runway) through one consistent set of commands — no need to learn each provider's quirks. - **Manage character consistency** — character profiles, reference sheets and the *story bible* carry identity and continuity between scenes; inspect generated results for drift. - **Review storyboard stills in your browser** — use the Review UI to inspect and select them. Director approval and exact queued spend authorisation are distinct gates; plain `produce` is live by default. - **Add the finishing touches** — narration, background music, subtitles, thumbnails, and vertical / square / looping variants for different platforms. - **Run many projects at once** and see them all on a dashboard: what's blocked, what's stale, what needs review, what's ready to publish. - **Record delivery evidence** — publish readiness requires a passing review report and `metrics.publishReady: true`; planned or previously film-reviewed projects also need current passing film-edit evidence. - **Preview the intended operation** — use each command’s documented planning or `--dry-run` path. There is no universal dry-run flag; queue compilation and direct rendering have different contracts. --- ## 🪜 How it works, step by step Here is the whole assembly line in plain words. Each step is a command, and each step saves its work to a file. | Step | Command | What actually happens | |---|---|---| | 1 | `init` | Create a new project folder to hold everything. | | 2 | `brief` | Turn your one-line idea into a short written brief. | | 3 | `storyboard` | Break the brief into scenes — and auto-build a **story bible** so characters, settings, and props stay consistent. | | 4 | *(director mode)* preflight + approval | Check for problems, then **wait for your "go"** before spending anything. | | 5 | `plan` | Pick the AI provider and prepare the exact request to send. | | 6 | `produce` | Actually generate the clips. (Add `--dry-run` to rehearse for free.) | | 7 | `assemble` | Stitch clips + narration + music into one MP4, then quality-check it. | | 8 | `review` | Record final review; explicit film plans require current full-playback evidence bound to the actual edit. Storyboard approval in the Review UI is a separate gate. | | 9 | `publish` | Mark it done and hand it off. | For new agent-led films, add a [structured film plan](./docs/SHARED_FILMMAKING_WORKFLOW.md) at storyboard time. It records format, purpose, shot action and performance; compiled prompts and final edit reviews detect relevant changes before reuse. The host agent manages phases and progress. You don't always run these by hand — `vclaw video create` can do the whole front of the line in one shot — but this is the path everything follows underneath. --- ## 🧩 The main parts, explained simply videoclaw is made of a few moving pieces. Here's each one in everyday terms: | Part | In plain terms | |---|---| | **The project folder** (`projects//`) | A single folder that holds *everything* about one video — the brief, storyboard, clips, approvals, history. This folder is the **source of truth**; the commands are just a tidy way to work on it. | | **Stages & checkpoints** | The assembly-line steps above. Each one writes a file and records that it finished, so you can replay or rewind any stage safely. | | **Two modes: storyboard vs director** | *Storyboard mode* is fast and runs straight through. *Director mode* adds the "stop and approve" gate — it won't render for real until you say so. | | **The Review UI** | A small web page (`vclaw video review-ui`) where a human looks at the storyboard stills and clicks **approve** or **regenerate**. No code needed. | | **Characters & the Story Bible** | Reference tools that help maintain the same people, places and props across scenes; generated consistency still needs review. The *story bible* is an auto-written "continuity reference" for the whole project. | | **Assembly** | The step that turns raw clips into a polished, narrated MP4 — adds a title card, TTS narration, slide animation, music, then runs an automatic **media quality check** on the result. | | **Providers** | The AI engines that actually make the video (Veo, Seedance, Runway). videoclaw routes to the right one and **never silently switches** if it fails. | | **Portfolio & ops** | Dashboards for when you have many projects — `status`, `metrics`, `next-actions`, and a `doctor` that tells you the single safest next step. | | **Obsidian workspace** | The same project data, rendered as browsable notes you can read in Obsidian instead of the terminal. | | **Skills** | Pre-built, ready-to-run workflows for common jobs (make a presenter video, clone an ad, build a character) that an AI agent can invoke. | That's the whole picture. Everything below is **reference detail** for power users, people running vclaw day to day, and AI agents — you can stop here and still use the tool. --- ## 🚀 Quickstart ### Install **Option A — the published package (fastest):** ```bash npm install -g videoclaw@alpha # Node >=20.10; installs the `vclaw` command vclaw video providers # show which AI providers are ready ``` No global install? Run it on demand with `npx -p videoclaw@alpha vclaw video providers`. **Option B — from a source checkout** (to hack on it or run the test suite): ```bash git clone https://github.com/davendra/videoclaw-v3 && cd videoclaw-v3 npm ci # Node >=20.10; locked dependencies npm run build # compile the CLI node dist/cli/vclaw.js video providers # show which AI providers are ready ``` The package and source checkout expose the same core CLI commands. Optional workflows also need their own runtimes: **FFmpeg/ffprobe** for local media work, **Python 3.12+** and workflow dependencies for Python helpers, **Bun >=1.3.5** for the Flow sidecar, and the **sqlite3 CLI** for local lane coordination. Provider renders additionally require the selected route's credentials and account. Bundled resource files do not install those runtimes or sidecar dependencies. See [installation and optional runtime setup](./docs-site/guide/install.md). Contributor checks need Python and FFmpeg even when no provider is contacted: ```bash python3.12 -m venv .venv source .venv/bin/activate python -m pip install -r requirements-test.txt npm run check:test-python npm test ``` Install FFmpeg/ffprobe before that check; title/subtitle tests also need the font and shaping capabilities reported by `check:test-python`. A passing offline suite checks local contracts, not live provider access. Current verification and release limitations are recorded in [release readiness](./docs/RELEASE_READINESS.md). > The lifecycle examples below use the source-checkout form `node dist/cli/vclaw.js …`. If you installed the published package (Option A), use `vclaw …` instead. **Then explore the project stages with a sample project (no provider submission — keep `--dry-run`):** ```bash node dist/cli/vclaw.js video init demo node dist/cli/vclaw.js video brief --project demo --title "Demo" --intent "A 15s product tease" node dist/cli/vclaw.js video storyboard --project demo --scene "open on product" --scene "close on logo" node dist/cli/vclaw.js video plan --project demo node dist/cli/vclaw.js video produce --project demo --dry-run node dist/cli/vclaw.js video status --project demo ``` > **Discovery and authoring need no provider keys.** Planning/direct dry-run can report blocked readiness when assets or a locally configured route are missing; that is diagnostic output, not a successful render. Keep `--dry-run` on plain `produce` while exploring, read the blockers, and configure only the route you intend to use. A zero-call queue compiler and a direct execution preview have different prerequisites. Add `--auto-chain` to `produce`/`execute` to compile the whole storyboard as a continuity chain into the durable Cinema queue — zero provider calls: the first pending scene is `awaiting-quote`, every later scene stays `blocked` behind its predecessor's selected video, and each link enters exact quotation only when that source exists. `--enqueue` can be added alongside `--auto-chain` (it does not replace it); `--execute`, `--dry-run` and `--confirm-spend` are refused. Each queued task is then quoted, authorized and run one at a time with `vclaw video cinema-work --task ` — for `veo-useapi` the shipped `dist/cli/flow-quote-adapter.js` quotes from the account's own Flow price table, so the 0-credit free model authorizes at `--maximum-spend 0`; only `runway-useapi` explore submits provider-free with `--confirm-provider-call`. See "Draining a queued Flow task" in `docs/CLI_REFERENCE.md`. `vclaw video pool --project [--max-concurrent ] [--scenes ]` compiles pending scenes as independent tasks into the durable Cinema queue. The concurrency cap is recorded on the queue lane; compilation itself submits nothing. `--dry-run` previews without writing. `--execute` is retired and `--confirm-spend` is rejected for enqueueing. Quote, authorise and run the returned tasks through `cinema-work`, then review their candidates. Plain `produce` without `--auto-chain` retains its direct live execution path: use `--dry-run` to preview that path, and do not assume its director approval gate is the same as an exact Cinema spend authorisation. `vclaw video render-scenes --project [--method ] [--fallback-chain] [--continue-from ] [--scenes ]` is the **fallback-ladder** driver: it renders pending scenes **sequentially** and, per scene, walks a **fallback route ladder** — try the primary route; if the provider rejects it, escalate to the next route, and so on (the first route that succeeds wins). This productizes the hand-written `voice-render.mjs` / `chain.mjs` loops (render one scene, on rejection escalate to a fallback method, resumable across crashes). `--method` picks the primary route; `--fallback-chain` appends the project's `routePreference` / mode defaults as the fallback rungs (without it the ladder is just the primary — a plain sequential render). Resumable via `--continue-from ` (skips scenes below `i`) and already-selected scenes; spend-gated (`--dry-run` to plan, `--confirm-spend` to render). Contrast: `--auto-chain` = sequential + chained on one route; `pool` = parallel + independent on one route; `render-scenes` = sequential + per-scene route fallback. The same queue renders **image** assets, not just video. `vclaw video cinema-image-compile --project --job --route openai-images` turns an already-planned Cinema image job into an `image-generate` task (today that route renders from the prompt alone — a job carrying reference images is refused, and reference-locked identity work still goes through `cinema-image-ingest`), then `cinema-work --dry-run` shows the exact payload, `cinema-image-quote` prices it, the ordinary `cinema-authorize` binds it, and `cinema-work --confirm-spend` renders it. The result enters the same `cinema-image-review` human gate as an image produced out of band — so a render is never usable as a reference until someone has looked at it. See "Cinema image assets" in `docs/CLI_REFERENCE.md`. **Or just run the packaged pre-flight that does build + tests + smokes + guardrails for you:** ```bash npm run check:release-readiness-lite ``` --- ## 🎬 Production workflow (the three common jobs) Most people enter through one of three paths: 1. **Make a campaign video** — `create` the director project, open `review-ui`, lock real storyboard stills, attach artifact-backed 4K stills, then publish only after the saved review report has `verdict: "pass"` and `metrics.publishReady: true`. 2. **Review and fix a project** — use `status`, `next-actions`, `doctor-project`, and `review-ui` to find the single safest next step. 3. **Manage a portfolio** — use `metrics`, `report`, `export-csv`, and `sync-obsidian` to see blocked, stale, review-needed, and publish-ready work. The advanced command surface stays available, but production trust comes from one rule: a handoff is ready **only** when `review-report.json` has `verdict: "pass"` and `metrics.publishReady: true`. The simple `video review --verdict pass` command intentionally writes that approval for already-reviewed projects; for director storyboard-image handoffs, use `review-ui` or `review-autopilot` so `publishReady` is derived from locked scene candidates, artifact-backed 4K stills, and final assembly approvals. Full guide: [`docs/PRODUCTION_WORKFLOW.md`](https://videoclaw-docs.vercel.app/reference/PRODUCTION_WORKFLOW). Handoff checklist: [`docs/OPERATOR_HANDOFF.md`](https://videoclaw-docs.vercel.app/reference/OPERATOR_HANDOFF). --- ## 🤖 For AI agents > **You are landing in a TypeScript/Node >=20.10 CLI repo.** If you do nothing else, read these in order: > > 1. **[`CLAUDE.md`](./CLAUDE.md)** — non-obvious conventions, single-test command, review-state invariant, agent-first orientation. > 2. **[`AGENTS.md`](./AGENTS.md)** — autonomy directive, coding style, commit/PR format, security expectations. > 3. **[`docs/ARCHITECTURE.md`](https://videoclaw-docs.vercel.app/reference/ARCHITECTURE)** — layer map and the canonical project flow. > 4. **[`skills/catalog.json`](./skills/catalog.json)** — machine-readable skill surface (don't scrape markdown). > 5. **[`docs/MASTER_PLAN_ALIGNMENT.md`](https://videoclaw-docs.vercel.app/reference/MASTER_PLAN_ALIGNMENT)** — what ships today + honest remaining gaps. > > **Canonical entry skills** — start broad, specialize later: `video-framework` · `brand-presenter` > **Contracts** — `schemas/video/*.json` is the source of truth for artifact shapes. > **Tests** — `src/tests/*.test.ts` run via `node --test dist/tests/*.test.js`. > > **Don't:** edit `dist/` · drop `.js` extensions from relative imports (NodeNext ESM requires them) · > add silent fallback across materially different provider routes · commit `.omx/` / `.vclaw/` / secrets. ### Agent integration videoclaw is built as a target for agent hosts, not as an orchestrator. - **One-call discovery:** `vclaw schema --json` returns the full command contract. - **MCP server:** `vclaw mcp serve` exposes read-only state queries to MCP-aware hosts. - **Sample skills:** see `mcp/skills-pack/` for Claude Code skill templates. See [`docs/AGENT_INTEGRATION_RESEARCH.md`](https://videoclaw-docs.vercel.app/reference/AGENT_INTEGRATION_RESEARCH) for the design rationale. --- ## 🏗️ Architecture The system is layered: a thin command-line front, a domain core that does the real work, and an adapter tier that talks to the AI providers. Each stage writes to the artifact/checkpoint/event ledger on disk.

videoclaw architecture layers — you or an agent at the top, CLI dispatching into domain modules, artifacts/checkpoints/events fanning out, execution runtime feeding the adapter layer, adapter layer branching into native transport, command shim, and custom adapter

Show diagram source (Mermaid) ```mermaid flowchart TB U[👤 Operator / AI agent] U -->|vclaw video ...| CLI["src/cli/vclaw.ts
single entrypoint"] CLI --> CORE["src/video/*
domain modules"] CORE --> ART[Artifacts · JSON] CORE --> CKPT[Checkpoints · stage state] CORE --> EVT["Events · events.jsonl"] CORE --> RT[Execution runtime] RT --> PP[provider-platform/
route descriptors] RT --> PM[pipeline-manifests/
storyboard · director] RT --> ADP[Adapter layer] ADP -->|built-in binary| NAT["Native transports
Seedance · Veo"] ADP -->|command shim| CMD["_SUBMIT_CMD
_POLL_CMD · _CANCEL_CMD"] ADP -->|custom override| EXT["VCLAW_*_ADAPTER
external binary"] CORE -. validates against .-> SCH["schemas/video/*.json"] CORE --> OBS[Obsidian export / sync] CORE --> REP[Reports · CSV · Snapshots · Diffs] ```
- **CLI layer** — argparse + dispatch only; no business logic. - **Domain layer** (`src/video/*`) — small, single-purpose modules. Each file owns one concept (artifacts, checkpoints, readiness, execution-plan, execution-runtime, doctor, metrics, next-actions, project-index, obsidian-export, etc.). - **Provider platform** — route descriptors for `veo-useapi`, `seedance-direct`, `runway-useapi`, `dreamina-useapi` (registered, not pursued since 2026-09-09), `magnific-rest`, `reapi-seedance` (Seedance 2.5 "Less Restriction" via reAPI — paid per second, opt-in, the one route that accepts a real photograph as the subject), `seedance-modelark` (BytePlus ModelArk Seedance 2.5, paid, opt-in). - **Adapter layer** — three resolution strategies (custom binary → built-in adapter with command shim → native in-process transport). Explicit fall-through, never silent. - **Schemas** — JSON Schema contracts under `schemas/video/` are the source of truth for every artifact shape. --- ## 🔁 Project lifecycle

Video production lifecycle — horizontal flow from init through brief, storyboard, readiness, plan, produce, review, to publish, with a director-mode preflight and approval-gate sub-branch descending into plan

Show diagram source (Mermaid) ```mermaid flowchart LR init([init]) --> brief([brief]) brief --> sb([storyboard]) sb --> ready{{readiness}} ready -->|storyboard mode| runPlan([plan / produce]) ready -->|director mode| pre{{director-preflight
content · refs · pronouns}} pre -->|hazards| fix[auto-fix or
storyboard-review] fix --> pre pre -->|pass| gate{{approval gate
produce --approve}} gate -.awaiting-approval.-> ops[(ops queue:
needs-review)] gate -->|approved| runPlan runPlan --> execStatus([execute-status
poll adapter]) execStatus --> ingest[[ingest outputs]] ingest --> assets([assets]) assets --> review([review]) review --> publish([publish]) execStatus -. you .-> cancel([execute-cancel]) ```
### On-disk shape of a project ```text projects// ├── project.json # manifest: slug, mode, state, metadata, execution profile ├── artifacts/ │ ├── brief.json # canonical brief │ ├── storyboard.json # scenes + character bindings │ ├── story-bible.json # deterministic continuity reference (cast · settings · props · timeline) │ ├── asset-manifest.json # per-scene assets │ ├── clone-plan.json # optional: template → clone decisions │ ├── execution-plan.json # selected route + payload │ ├── execution-report.json # submit · poll · output ingest │ ├── readiness.json │ ├── character-consistency.json │ ├── review-report.json │ ├── publish-report.json │ ├── analyze-output.json │ └── history/ # append-only artifact snapshots ├── checkpoints/ # brief · storyboard · assets · review · publish (+ state) ├── events/events.jsonl # append-only timeline ├── characters/characters.json # optional GB-anchored profiles ├── storyboard.md # director-mode approval review (human-readable) └── state/ # derived state cache ``` --- ## 🧭 Production modes Every command accepts `--mode storyboard|director`. The mode drives the pipeline manifest and the gate semantics. | Dimension | `storyboard` mode | `director` mode | |---|---|---| | Default stage set | init → brief → storyboard → assets → review → publish | Same, **plus** preflight + approval gate before execution | | Approval gate | none | `produce --approve` (or `VIDEOCLAW_APPROVE_STORYBOARD=1` unattended) required before provider submission | | Storyboard review file | optional | `projects//storyboard.md` auto-generated with character binding table and cost estimate | | Preflight checks | readiness + character-consistency | + content-hazard detection · GB-id validation · remote-ref probe · pronoun drift · repeated-scene warnings | | Preflight bypasses | n/a | `DIRECTOR_AUTO_FIX_CONTENT=1` (rewrite hazards) · `SKIP_DIRECTOR_PREFLIGHT=1` | | Ops visibility | `active` | `awaiting-approval` → surfaced as **`needs-review`** across index · metrics · dashboards | The normalized **review-state ladder** (`missing` → `current` → `stale`) flows through `status`, `index`, `report`, `export-csv`, Obsidian export, dashboards, next-actions, snapshot diffs, and the doctor layer. **A stale director review blocks `execute`/`execute-status` even if approval is set** — review freshness is a first-class runtime invariant. --- ## 🔌 Provider routing

Provider routing decision tree — starts with the selected route, branches on whether a custom adapter is set, whether a built-in adapter supports the route, whether a command shim is configured, and whether native credentials are available; hard-fails if none of the paths resolve

Show diagram source (Mermaid) ```mermaid flowchart TD Start[["route ∈ { veo-useapi · seedance-direct · runway-useapi ·
dreamina-useapi · magnific-rest · seedance-modelark · reapi-seedance }"]] Start --> Q1{"VCLAW_*_ADAPTER set?"} Q1 -->|yes| Custom[["Custom adapter binary
stdin → JSON, stdout → JSON"]] Q1 -->|no| Q2{"Built-in adapter supports route?
(all seven routes ship one)"} Q2 -->|no| Fail([["❌ hard fail
no silent fallback"]]) Q2 -->|yes| Q3{"_SUBMIT_CMD / _POLL_CMD set?"} Q3 -->|yes| Shim[["Command shim
through built-in adapter"]] Q3 -->|no| Q4{"Native creds available?
SUTUI_API_KEY or the free Higgsfield engine (seedance) · local vclaw-cli (veo) · USEAPI_API_TOKEN (runway, dreamina) · MAGNIFIC_API_KEY (magnific) · ARK_API_KEY (modelark) · VCLAW_REAPI_SEEDANCE_VIA + TREG_TOKEN or REAPI_API_KEY (reapi)"} Q4 -->|yes| Native[["✅ Native in-process transport"]] Q4 -->|no| Fail ```
### Environment variables | Variable | Used by | Purpose | |---|---|---| | `VCLAW_VEO_USEAPI_ADAPTER` | veo-useapi | custom adapter binary override | | `VCLAW_SEEDANCE_DIRECT_ADAPTER` | seedance-direct | custom adapter binary override | | `VCLAW_RUNWAY_USEAPI_ADAPTER` | runway-useapi | custom adapter binary override | | `VCLAW_SEEDANCE_DIRECT_SUBMIT_CMD` · `_POLL_CMD` · `_CANCEL_CMD` | seedance-direct | command shim through built-in adapter | | `SUTUI_API_KEY` | seedance-direct (native) | XSkill API credentials for in-process transport | | `VCLAW_MAGNIFIC_REST_ADAPTER` · `_SUBMIT_CMD` · `_POLL_CMD` · `_CANCEL_CMD` | magnific-rest | custom adapter override / command shim | | `MAGNIFIC_API_KEY` | magnific-rest (native) + `finish --backend magnific-precision` | Magnific/Freepik REST key (`x-magnific-api-key`) for video generation + upscale | | `VCLAW_MAGNIFIC_MODEL` · `VCLAW_MAGNIFIC_API_URL` | magnific-rest | proxied image-to-video model (default = cheapest catalog model fitting the op; premium `kling-o1-pro` opt-in; unknown ids throw) · API base override | | `ARK_API_KEY` | seedance-modelark (native) | BytePlus ModelArk API key (Bearer) for the official Seedance 2.5 / 2.0 API — paid per second; never the xskill `SUTUI_API_KEY` | | `VCLAW_MODELARK_MODEL` · `VCLAW_MODELARK_BASE_URL` | seedance-modelark | `dreamina-seedance-2-5-260628` (default) / `dreamina-seedance-2-0-fast-260128` / `dreamina-seedance-2-0-mini-260615`; unknown ids throw · API base override | | `VCLAW_MODELARK_CHAIN_MODE` | seedance-modelark | `first-frame` (default) or `extend` — an `extend` chain sends the previous clip itself as `@Video 1` and bills its seconds as input; part of the `--require-contract` fingerprint | | `VCLAW_SEEDANCE_MODELARK_ADAPTER` · `_SUBMIT_CMD` · `_POLL_CMD` · `_CANCEL_CMD` | seedance-modelark | custom adapter override / command shim | | `VCLAW_REAPI_SEEDANCE_VIA` | reapi-seedance | `treg` or `direct` — which credential (and so which account) pays; never inferred, unset = the route is blocked | | `TREG_TOKEN` | reapi-seedance (`via=treg`) | treg relay token; also hosts local references | | `REAPI_API_KEY` · `GO_BANANAS_API_KEY` | reapi-seedance (`via=direct`) | reAPI key, plus Go Bananas R2 for reference hosting | | `VCLAW_REAPI_SEEDANCE_RESOLUTION` | reapi-seedance | probe tier (e.g. `480p`); part of the approval fingerprint | | `VIDEOCLAW_APPROVE_STORYBOARD` | director mode | `=1` approves the storyboard for an unattended run (the interactive form is `produce --approve`) | | `DIRECTOR_AUTO_FIX_CONTENT` | director mode | `=1` to rewrite provider-risk phrases in storyboard | | `SKIP_DIRECTOR_PREFLIGHT` | director mode | `=1` to bypass preflight (use sparingly) | | `DIRECTOR_STRICT_PROMPT_QUALITY` | director mode | `=1` to promote prompt-quality warnings to blockers | | `DIRECTOR_STRICT_DIALOGUE_FIT` | director mode | `=1` to promote dialogue-duration warnings to blockers | | `GEMINI_API_KEYS` · `GOOGLE_API_KEYS` · `GOOGLE_API_KEY` | analyze-template / analyze | Gemini key pool (round-robin with per-key cooldown) | | `VCLAW_GEMINI_API_ENDPOINT` | Gemini pool | override HTTP endpoint (local or alt Gemini-compatible) | | `VCLAW_GEMINI_VIDEO_PROCESSING` | analyze --auto | default processing mode, `static` (sampled frames) or `agentic` (whole video via the Interactions API); `--processing` wins | | `VCLAW_GEMINI_AGENTIC_MODEL` | analyze --auto --processing agentic | Interactions model (default `gemini-3.8-flash`); `--gemini-model` wins | | `VCLAW_GEMINI_AGENTIC_MODELS` | analyze --auto --processing agentic | comma list extending the agentic-capable model allowlist | | `VCLAW_GEMINI_API_BASE` | Interactions + Files API | base URL override for the agentic path (not `generateContent`) | | `GO_BANANAS_API_KEY` | preflight | validate stored character GB-id anchors | ### Google Flow inline @-markers (veo-useapi) useapi.net's Google Flow v1 API (blog 260609) accepts **inline `@`-mention markers** in prompt text that anchor a body-slot reference to a position in the prompt: | Marker | Index range | Endpoint | |---|---|---| | `@character_N` | 1–7 | `POST /videos` and `POST /images` | | `@referenceImage_N` | 1–7 | `POST /videos` | | `@referenceAudio_N` | 1–5 | `POST /videos` | | `@reference_N` | 1–10 | `POST /images` | Markers are **case-insensitive** and **opt-in** (a slot without a marker is fine; a marker without a matching body slot makes the API 400). The grammar is reserved through videoclaw's prompt pipeline (`@Name` tag resolution preserves the tokens verbatim, like `@imageN`) and is **veo-useapi-route-only** — on any other route the tokens are stripped from the scene prompt with a warning. V2V deliberately has **no** marker (`referenceVideo_1` stays flag-only via `--ref-video`). Helper module: `src/video/flow-markers.ts`; full details in [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE). **Auto-injection:** on veo-useapi, when a scene's prompt tags a character that has a registered Flow ref (`flow-characters.json`), `buildExecutionPayload` rewrites the `@Name` tag into its canonical `@character_N` marker automatically. Slot order = scene cast order first, then tag-only characters (capped at 7, overflow warned); hand-authored markers pass through untouched. Cast-name matching stays **exact-case** (the legacy lookup, verbatim) — which is exactly why a tagless prompt produces a byte-identical payload; only `@Name` **tag** matching is case-insensitive (`@mascot` resolves to a registered `Mascot`). Note that a ref-registered character's tag no longer also attaches its loose portrait image — the saved Flow character bundles its identity images. Characters without a Flow ref keep the normal descriptor substitution (including portrait collection). --- ## 🧰 Command surface Full reference: [`docs/CLI_REFERENCE.md`](https://videoclaw-docs.vercel.app/reference/CLI_REFERENCE). Condensed groups: ### Lifecycle `init` · `create` · `auto` · `iterate` · `run-pipeline` · `brief` · `storyboard` · `assets` · `review` · `publish` · `approve` (deprecated since 3.0.0-alpha.13 — use `produce --approve`) ### Readiness · planning · runtime `readiness` · `plan` (alias `execution-plan`) · `produce` (alias `execute`) · `execute-status` · `execute-cancel` · `execute-abandon` · `execute-bind` · `director-preflight` · `storyboard-review` · `review-ui` · `review-autopilot` **When a submission's answer is lost.** A create that never returned an id leaves the scene `submit-unknown` — the provider task may exist and may be billing. `execute-status` looks it up in the provider's own task list and binds it when exactly one candidate sits in the window. When it cannot decide (several candidates, a window it could not search, no recorded intent time), read the task id off the provider console and name it: ```bash vclaw video execute-bind --project --task # shows what it would bind vclaw video execute-bind --project --task --confirm-bind # does it ``` It makes no submission and never re-submits: the task is read once and bound only if it exists, names this job's model, is not already owned by another job, and the scene's output path is not already another run's clip. `seedance-modelark` only. `execute-abandon` remains the exit when the task cannot be named — it stops the waiting without cancelling anything. `review-ui` is the local human-in-the-loop station for the Seedance storyboard workflow documented in [`docs/REFERENCE_VIDEO_SEEDANCE_MOTION_DESIGN_WORKFLOW.md`](https://videoclaw-docs.vercel.app/reference/REFERENCE_VIDEO_SEEDANCE_MOTION_DESIGN_WORKFLOW). Use its director defaults to save a production ledger that follows the still-frame-first, start/end-frame, bridge-pose, variant-pass, and post-retiming recipe. It binds to loopback by default and uses a one-time launch token plus an HttpOnly session cookie; non-loopback hosts require an explicit `--allow-remote`, and wildcard binds are refused. Treat the printed launch URL as a credential. `review-autopilot` lets the agent do that handoff without manual clicks once storyboard still candidates exist. It locks the best available stills, promotes artifact-backed upscaled handoff assets, fills the reference and assembly gates, and writes the same review artifacts as the browser station. **Live run dashboard** (`vclaw video portal --surface run` → `run.html`) is the operations view of a render: one card per generation (storyboard scene) with a STATUS badge (`done`/`rendering`/`pending`/`failed`), the provider job id + error, the input keyframe, a playable in-progress clip (`outputs/scene-N.mp4`), the exact submit prompt + contract, a spend estimate, and an event log — auto-refreshing so an open tab stays current. It paints a RED **diff-vs-contract alarm** when the payload that was actually submitted has diverged from the current contract (the class of bug where an `@tag` silently hijacks the references), or when the packet's provider settings (resolution, duration, prompt variant, slot plan) moved after submit, backed by a frozen `artifacts/run-contract.json` snapshot that `produce`/`execute` persists at submit time. `run.html` is part of the default `vclaw video portal` surface set and is regenerated automatically on every `produce`/`execute` and `execute-status` poll (`VCLAW_NO_RUN_SURFACE=1` opts out). ### Templates · cloning · storyboard templates `analyze` (`analyze-template` is a deprecated spelling) · `template-save` (`template-create` is a deprecated spelling) · `template-list` · `template-show` · `template-validate` · `clone-plan` · `clone-init` · `clone-execute` (`clone-ad` is a deprecated spelling) · `storyboard-from-clone` · `storyboard-template-list` · `storyboard-template-show` ### Character subsystem `character-add` · `character-list` · `character-show` · `character-consistency` · `consistency-audit` · `motion-qc` · `clip-qc` · `keyframe-qc` · `character-auto-create` · `environment-auto-create` · `character-import-library` · `find-library` · `library find` (deprecated spelling of `find-library`) · `library clean` · `list-library` · `seedance-register-assets` · `flow-register-characters` · `flow-register-voices` · `flow-r2v` · `voice-clone` · `show-bible` · `show-preflight` `consistency-audit` is the **automated character identity/costume vision audit**: for each rendered scene it extracts a representative mid-frame and asks an (injectable, Gemini-backed) vision client whether each registered scene character still matches its locked reference face/hair AND costume/colours, plus a deterministic dark-border check and an extra-figure flag — catching wardrobe/identity drift (a dhoti rendering crimson in one scene and tan in another) BEFORE a render is presented as done. It writes `consistency-audit.json` and also runs advisory/non-fatal at the end of a real `produce`/`execute` run when a Gemini key is configured. `motion-qc` is its sibling for **rendering artifacts a still-frame QC pass is blind to**: it samples K dense frames per rendered clip (default 9) and runs a per-frame lane (breath-vapour condensation puffs, film grain rendering as drifting fog over dark regions) plus an adjacent-pair lane (objects/faces **morphing** between moments, solid props **vanishing** mid-clip — anchored on the scene keyframe when bound). Conservative prompts, advisory on transport failure, `clipChecked:false` for image-only/unrendered scenes. Writes `motion-artifact-qc.json`; requires a Gemini vision key. See `docs/CLI_REFERENCE.md`. `clip-qc` is the third lane: a **per-second headcount** over every rendered clip. `consistency-audit` samples one mid-frame and `motion-qc` looks for morph/vanish artefacts — neither counts people, so invented, duplicated, or edge-entering cast is invisible to both (eight clips of a 37-shot film shipped that way). Flags `headcount-variance` (the count changes mid-clip) and `headcount-exceeds-cast` (more people than the scene names), and writes a filmstrip contact sheet per clip to `projects//qc/` — that lane needs no vision key. Writes `clip-qc.json`. See `docs/CLI_REFERENCE.md`. `keyframe-qc` is the **fail-fast PRE-render keyframe readiness gate** — deterministic and offline (pure Node PNG IHDR header parse; no vision model, no spend). Given the storyboard's scene count it verifies every scene has `references/scene-keyframe.png`, that each is a readable PNG, and that all keyframes share the dominant WxH; a missing storyboard, missing/unreadable keyframe, or dimension mismatch fails the gate (exit 3, GATE) so an `&&` chain halts BEFORE `produce` spends on drifted keyframes. A uniform-but-non-1280x720 set passes with an advisory. Writes `keyframe-qc.json`. ### Portfolio · ops · reporting `list` · `index` · `metrics` · `workload` · `next-actions` · `dependencies` · `status` · `doctor-project` · `doctor-portfolio` · `report` · `report-snapshot` · `report-history` · `report-diff` · `trends` · `export-csv` · `artifact-history` · `verify-env` · `cost-estimate` ### Mission Control - `vclaw video monitor` — Mission Control: a live localhost cockpit across every project and provider. - `vclaw video migrate-home [--confirm] [--root ]` — (deprecated since 3.0.0-alpha.13, one-shot) consolidate scattered projects (`~/.videoclaw-*` roots) into the one canonical workspace home (`~/videoclaw`) via `mv` + a symlink left at the old path. Dry-run by default; `--confirm` performs the moves. Collision-safe and idempotent. ### Metadata `set-meta` · `set-execution-profile` · `import-legacy` (deprecated, historical v2 import) ### Post-production `remix-narrated` · `verify-final` · `qc` · `make-vertical` · `make-square` · `make-loop` · `thumbnail` · `archive-project` · `motion-overlay` · subtitle burn-in `vclaw video match-highlights --source