HaD0Yun/CozyClay

What It Does

CozyClay is a browser previs studio for planning shots before paying for AI video generation. You block a set from primitives, add rigged characters or capsule stand-ins, describe motion for an agent to compile, and arrange shots on a timeline with camera moves and cuts. The export is designed as input for a video model: first and last frames, a greybox reference clip, camera data, depth and normal passes, a contact sheet, OTIO cut list, and a prompt describing the framing (3).

The problem it targets is prompt drift: a text prompt cannot pin down blocking, timing, or camera position, so each failed take costs money. By deciding those in 3D first, the video model receives a reference that constrains the shot instead of guessing (15).

It is aimed at animators, previs artists, and AI video creators who want directable shots rather than text-only generation. A Storyboard mode supports still-panel planning with captions and an animatic for teams that prefer that workflow (21).

Quick Start

You need Node.js 22.19 or newer and a Chromium browser. No GPU, Python, or model download is required (3).

Run the published package:

npx cozyclay

Then open http://127.0.0.1:5180/app/ to enter the studio (17). To work from source instead:

git clone https://github.com/NomaDamas/CozyClay.git && cd CozyClay
npm install
npm run dev     # http://127.0.0.1:5180/app/
npm test

From the studio, build a scene, direct motion through the agent panel (Cmd/Ctrl+B), set shots, and export a keyframe pack for your target video model (22).

Directing With AI

Three surfaces drive the same live scene: an in-studio agent panel that accepts ChatGPT sign-in or your own Anthropic, OpenAI, Gemini, MiniMax, OpenRouter, or CLIProxyAPI key; an MCP server via npx -y cozyclay mcp for Claude Desktop, Claude Code, Cursor, or other MCP clients; and a terminal interface (cclay live status --wait) that emits JSON for coding agents (22). Configure the MCP server with:

{ "mcpServers": { "cozyclay": { "command": "npx", "args": ["-y", "cozyclay", "mcp"] } } }

Constraints

• License: AGPL-3.0-or-later; additional licensing terms and third-party notices are documented separately (40).
• Runtime: Node 22.19+, Chromium browser. Running npx cozyclay fetches the newest release on each launch; one-click in-app updates are disabled on Windows by design, where the chip provides a command to copy instead (3).
• Telemetry: Anonymous telemetry is documented, with an opt-out via cclay telemetry off (32).
• AI provider keys: The agent panel requires signing in with ChatGPT or supplying a provider key; the project does not include model weights or a video generator.

Docs

Key references include the agent setup guide, motion spec and QA guide, cclay live CLI docs, MCP tool reference, studio UI map, and privacy notes. Background guides cover greybox-to-video workflow and camera control for AI video.

HotRepo's take

CozyClay recorded 49 new stars in the daily JavaScript snapshot on 2026-11-06, with a best position of 13 on that day's language list. That is a single day of data, so it supports noting a spike in attention around that snapshot but not a trend conclusion. The technical story is concrete: a deterministic motion compiler with QA, multi-surface agent access via MCP and CLI, and exports shaped to specific video-model inputs. The AGPL-3.0 license and the requirement to bring your own model keys are the main practical considerations for adoption.