sarpstar/cinecode

What it is

cinecode is a skill for AI coding agents, not a standalone renderer. Installed into Claude Code or Cursor, it walks an agent through planning, writing, and building a film where every frame is generated in code — Canvas 2D for the self-contained quick mode, or three.js/WebGL scenes for the longer film mode — then renders frames in headless Chrome and muxes video and audio with ffmpeg. The output is a finished <title>.mp4 in the film's folder.

It targets short films, YouTube documentaries and explainers, ads and product films, vertical social clips, and music videos cut to a track's beat grid. The agent asks questions, proposes a mode and purpose (cinematic or ad/product), shows a plan and two sample frames before building, and iterates on drafts.

The kit also carries craft guidance the agent consults: camera-move vocabulary, typography rules, writing and hook checks, sound design, and a library of 58 style recipes. Verification helpers (make.py, qc.py) check the first-frames motion, audio loudness, and per-scene readability.

Install and first film

Prerequisites: an agent that can run local tools (Claude Code desktop, VS Code extension, or terminal; Cursor also works), plus Node.js 22+, Python 3.9+, ffmpeg, and Chrome/Chromium/Edge on a machine with a usable GPU. Missing pieces are offered for install with your approval.

In Claude Code, the simplest path is to tell the agent to install the skill from the repository. Manually:

git clone https://github.com/sarpstar/cinecode.git ~/.claude/skills/cinecode

For Cursor, clone to ~/.cursor/skills/cinecode instead. Install only one copy.

Then open an empty folder as the film workspace and start a chat with a request such as:

cinecode ile bir film yapalım: <what it should tell, one or two sentences>.

You can optionally add duration, aspect/where it will be shown, voiceover/music, and a look reference; leave anything blank and the agent asks. Answer the mode/purpose and short question rounds, approve or adjust at each checkpoint, and the final film lands at the top of the film folder as <title>.mp4. Quick mode targets roughly under-three-minute pieces in one session; film mode runs longer pieces through staged approvals.

Constraints and limits

• Claude Code is the fullest experience: guard hooks that stop unapproved steps run only there. Cursor gets the same make.py/qc.py checks but not the guard hooks.
• Hooks need a recent Claude Code (exec-style hooks and onFailure, 2.1.295+); on older versions the guard may not engage, though films still run.
• Rendering uses headless Chrome; without GPU access it falls back to CPU, which is fine for tests but slow for full films.
• Quick mode needs a few hundred MB of disk; film mode needs several GB per film during render.
• Voiceover needs a Gemini API key entered once (or one of the optional Turkish TTS models). Search-related features (references, music, first font/style downloads) need network access; render, mix, and checks work offline.
• Windows is tested for the test suite, but a full film has not yet been run end-to-end on Windows per the README.
• Generated visuals are code-rendered; faces work best stylized or as silhouettes. External image/video generators are only used if you connect one yourself.
• Licensing: the kit is MIT. Fonts, music, and assets carry their own licenses, recorded in LICENSES.csv; a credits file is written beside each final. Commercial use is allowed kit-side, but you remain responsible for your own logos, brand fonts, footage, and songs — not legal advice.

HotRepo's take

On 2026-11-04 the project entered HotRepo's new-project list with 148 stars and 29 forks, adding 36 stars and 7 forks during the recorded roughly one-hour growth window. That is a single snapshot, so it supports only that-day interest, not a trend. The notable structural bet is treating filmmaking as a coding task: the agent writes timeline functions and checks frames, and the skill supplies craft constraints rather than a model. Whether that produces usable output depends on the agent's adherence to the referenced guidance, which the project handles through guard hooks and quality checks on Claude Code specifically.

Project source and documentation