showtime

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/readme/hero-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/readme/hero-light.svg">
    <img alt="showtime: velvet curtains open on a lit stage. A local video studio for your coding agent. Describe a video. Your agent directs. Your machine renders." src="assets/readme/hero-light.svg" width="100%">
  </picture>
</p>



https://github.com/user-attachments/assets/1132aa71-7fe5-4345-a925-790d80462fda


<p align="center"><sub>The 0.3.0 showreel: 50 seconds, rendered by showtime 0.3.0 on one machine; every shot names the feature it uses (<a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_showreel/README.md">about the film</a>).</sub><br><sub><a href="https://github.com/FavioVazquez/showtime-examples/releases/download/examples-media-v1/_showreel--showreel-16x9.mp4"><b>Download the 50-second showreel</b></a> (full quality, 41 MB). Music: “Born Of The Sky” by Scott Buckley, <a href="https://creativecommons.org/licenses/by/4.0/">CC BY 4.0</a>. CO2 data: NOAA GML / Scripps (<a href="https://github.com/FavioVazquez/showtime-examples/blob/main/examples/_showreel/credits.txt">credits</a>).</sub></p>
<!-- /HERO -->

<p align="center">
  <a href="LICENSE"><img alt="license: MIT" src="assets/readme/badges/license.svg" height="24"></a>
  <img alt="runs on your machine" src="assets/readme/badges/local.svg" height="24">
  <img alt="API keys: none" src="assets/readme/badges/keys.svg" height="24">
  <a href="#works-with"><img alt="tested with Claude Code, Codex, Cursor, Devin and OpenCode" src="assets/readme/badges/agents.svg" height="24"></a>
  <a href="CHANGELOG.md"><img alt="status: 0.3, early" src="assets/readme/badges/status.svg" height="24"></a>
  <a href="#requirements"><img alt="tested: Intel Mac, Apple Silicon, Linux x64, Linux arm64, Windows x64, Windows 11 on Arm" src="assets/readme/badges/tested.svg" height="24"></a>
  <a href="#requirements"><img alt="still to run: Windows 10/11 desktop" src="assets/readme/badges/windows.svg" height="24"></a>
</p>

<h3 align="center">A local video studio for your coding agent.<br>Describe a video. Your agent directs. Your machine renders.</h3>

<p align="center">
Motion graphics, voice-over, music, sound design, captions, footage editing and platform exports,
with no cloud AI services, no API keys and no uploads. Works in Claude Code, Codex, Cursor, Devin,
OpenCode and any agent that supports <a href="https://agentskills.io">Agent Skills</a>.
</p>

<p align="center">
  <a href="#quick-start"><b>Quick start</b></a> ·
  <a href="#works-with"><b>Works with</b></a> ·
  <a href="#now-showing"><b>Gallery</b></a> ·
  <a href="#how-it-works"><b>How it works</b></a> ·
  <a href="#meet-the-crew"><b>The crew</b></a> ·
  <a href="#studio-mode"><b>Studio</b></a> ·
  <a href="#what-you-get"><b>Formats</b></a> ·
  <a href="docs/README.md"><b>Docs</b></a> ·
  <a href="https://faviovazquez.github.io/showtime/"><b>Site</b></a> ·
  <a href="#requirements"><b>Requirements</b></a>
</p>

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  <img alt="" src="assets/readme/divider-light.svg" width="100%">
</picture>

## Quick start

**1. Install the two prerequisites** (details in [Requirements](#requirements)):
[uv](https://docs.astral.sh/uv/) and [Node.js](https://nodejs.org) 24 or 22 LTS (20 or newer works).
Restart your coding agent afterwards so it sees them.

**2. Add showtime to your agent.** In Claude Code:

```text
/plugin marketplace add FavioVazquez/showtime
/plugin install showtime@showtime
```

Using Codex, Cursor, Devin, OpenCode or another agent? [Works with](#works-with) has the exact
install for each, and `npx skills add FavioVazquez/showtime` covers any agent that supports Agent Skills.

**3. Ask for a video:**

```text
Make a 20-second launch video for this repo, with a voice-over and upbeat music.
```

The first time, your agent checks what is missing, tells you the download size and time (about
0.6 to 0.8 GB into `~/.showtime`, depending on your system, usually 2 to 6 minutes; nothing outside that
folder changes) and runs setup once you say yes. Bigger pieces (the transcription model, Manim, music
tracks) come the first time a video needs them, announced with their size. After that, a request in Claude
Code looks like this:

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="assets/readme/terminal-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="assets/readme/terminal-light.svg">
    <img alt="A Claude Code session: the request is typed, Claude states its assumptions (quick mode, 20 s, 16:9, English voice, upbeat bed, only claims the README makes), shows a first look, renders on this machine, and showtime prints its completion card: final.mp4 is ready, 20.0 s, 1920x1080, 17.0 MB, qa PASS, the output path and the next step." src="assets/readme/terminal-light.svg" width="100%">
  </picture>
  <br><sub>An illustration of a session in Claude Code; other agents show the same steps in their own style. The card's figures are example 01's; render time depends on your machine.</sub>
</p>

Your agent states its assumptions in one line (it asks only when a request is genuinely open), shows you a
first look (stills or a fast draft) before the full-quality render, then checks the result with
`showtime qa`. Every request gets its own folder, `showtime-out/<name>-<timestamp>/`, with `final.mp4`,
`poster.jpg`, `share.txt`, `exports/` and `work/`. Nothing is ever overwritten.

> [!TIP]
> Say **"show me options first"** (or "studio") and your agent opens a local board where you pick a concept,
> a look, a music bed and a storyboard before anything is built. Say **"no crew"** to keep the whole job in
> one session.

**What's new in 0.3.0** (the full list is [below](#new-in-030)):

- **A full review on every video, and quieter runs.** Each finished video gets looks, qa and a critic round before
  delivery; say "lean" for a lighter pass. Commands print a short verdict and keep the detail in a file, references
  are read by the piece (`showtime guide`), and looks at frames go to a disposable reviewer, so less piles up in your
  agent's context.
- **Videos that differ from each other.** A local look history warns when a video repeats a recent one, and
  `showtime reference` learns pace and type scale from a video you like, never its content.
- **Checks for what viewers complain about.** A phone check (text you can read at phone size, held long enough),
  and pairwise review, where a new version ships only if the critic prefers it in both orders.
- **New kinds of video.** Repo and paper explainers, release and PR videos (`showtime release-video`, and a GitHub
  Action), launches that start from your product's real brand, and `showtime adopt` for video code you already have.
- **A receipt for every job:** your request as typed, the rounds, renders and time, and tokens and cost where your
  agent reports them.

In my blind vote in [benchmark](#benchmark) round 4, 0.3.0 in lean mode was preferred to 0.2.0 on 4 of 6 tasks and to
plain Claude Code on 7 of 8; the full-review default came after that round and was not part of it.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/readme/divider-dark.svg">
  <img alt="" src="assets/readme/divider-light.svg" width="100%">
</picture>

## Works with

showtime is a skill, a command line and an MCP server, so it runs in any coding agent that reads
[Agent Skills](https://agentskills.io) and can run shell commands. MCP adds typed tools on top, and
the ten [crew](#meet-the-crew) agents are an optional speed-up for hosts that have custom sub-agents.

**Tested with.** A real run passed: the agent installed showtime from this repository and made a
5-second test video ("make a 5-second test video that says hello", empty folder), ending in a `final.mp4`
whose `showtime qa` verdict had no FAIL.

| Agent | Install route | Crew agents | Tested with |
|---|---|---|---|
| [Claude Code](#claude-code) | plugin | yes | the primary host |
| [OpenAI Codex](#other-agents) | plugin | with `showtime install` | CLI 0.158.0, plugin route |
| [Cursor](#other-agents) | plugin (reads `.claude-plugin/`) | yes | CLI 2026.09.28 |
| [Devin](#other-agents) | plugin (reads `.claude-plugin/`) | yes (local only) | CLI 3000.11.3 |
| [OpenCode](#other-agents) | `showtime install` | yes | 1.18.33, a free model |

**Should work with** any agent that supports [Agent Skills](https://agentskills.io): GitHub Copilot
(CLI and VS Code), Gemini CLI, Antigravity, Cline, Kilo Code, Kiro, Zed, Goose, Amp, Factory Droid and Qwen
Code. The files each one reads are packaged and were checked with the agent's own tools where possible, but
no real video has been made in them yet. If you try one, an [issue](https://github.com/FavioVazquez/showtime/issues)
with what happened helps everyone. Exact steps for every agent, and what the tests covered:
[docs/agents.md](docs/agents.md).

### Claude Code

```text
/plugin marketplace add FavioVazquez/showtime
/plugin install showtime@showtime
```

Everything is included: the skill, the ten crew agents, the MCP server and the plugin settings (`/config`).

### Any agent that supports Agent Skills

```bash
npx skills add FavioVazquez/showtime
```

This installs the skill for the agents you pick. Then run setup once from the installed skill folder
(`<skills folder>/showtime/bin/showtime setup`), and add the MCP server if you want it ([below](#mcp-only)).

### Other agents

Agents often run in a sandbox that blocks a large download, so run setup yourself once, in a normal terminal
(it prints the size first and resumes if interrupted):

```bash
git clone --depth 1 https://github.com/FavioVazquez/showtime ~/showtime
~/showtime/skills/showtime/bin/showtime setup      # Windows: ~\showtime\skills\showtime\bin\showtime.cmd setu