The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Proofcut listing page.
An AI video editor that proves its cuts. Your recordings in, a finished, mastered film out: cut by transcript, with b-roll, cards, music and captions, and every step an agent can call. proofcut renders on your own machine, then transcribes the render and checks that it says what the edit says.
https://github.com/user-attachments/assets/4153d180-3d7c-4c70-af5f-54d63d0a8bd5
Above: an agent cutting a demo video, unattended. The two runs it was cut from, uncut (silent: the recorder took frames only, and the voice is in the film the agent cut): the workspace (2:26) and Claude Code with the proofcut plugin (3:09).
Most of the work in a narrated video, whether an essay, a tutorial, a screencast or a talk, is bookkeeping. Find the retakes and cut them clean. Put the right footage under each line. Level the music under the voice, caption it, end on a card, render it, master it. An agent can do that bookkeeping now, given an editor it can drive.
What an agent cannot do on its own is know that the file it rendered is the film it meant. ffmpeg, melt and auto-editor all exit 0 on some failures, so a render can drop a line, keep a retake, add a frame of black or carry no captions and still report success. Every check that reads the project rather than the file agrees with it. The usual way to find out is to watch the whole thing.
proofcut is an editor built around that gap. You, or an agent, edit a timeline addressed by the words in it. proofcut renders it on your machine, then transcribes the render, counts its frames, and says where the file and the edit disagree.
TRIAL.md scores three unattended runs, each handed a goal and no steps, and each passed every one of its checks:
One project, and proofcut's own commands from the first import to the delivered file. No NLE finishes the film, and nothing else touches the render. Each stage is one command, and each row links the section of the manual that walks it.
| Stage | Command |
|---|---|
| Bring in the voiceover and footage, and transcribe | import, transcribe |
| Cut retakes and asides by naming their words | cut vo 111:114 |
| Hang b-roll and cards off the lines they belong to | cue add, card new |
| Open cold on a scene, end on a card | head, tail |
| Play the footage's own lines in a gap, or under the narration | hold add, hold under |
| Score it: placed passages, crossfaded, levelled under the voice | music |
| Pull breaths down without cutting them | attenuate |
| Render and master to a loudness target | export --render --loudness -16 |
| Burn in captions, words fading or blurring in, spelled your way | captions --burn, caption-style --reveal, lexicon add |
| Check the render says what the edit says | verify, frames, hold check |
Two video essays of five to six minutes, first finished in Kdenlive, have been rebuilt with these commands alone and measured against the delivered files. One came out the same length to the frame. The other matched all 63 of its voiceover ranges to the millisecond, with the voice aligned to the sample. Both master at the original's −16 LUFS. The measurements are in HISTORY.md.
Beyond those stages:
cut vo 111:114 names the same words however many cuts came before it,
and a cue hung off a phrase stays addressed through every cut around it.shot-sheet draws the whole picture track as
one labelled grid, and footage-sheet browses a clip you haven't cut yet.
Both return the image itself over MCP, not a path the agent can't open.describe writes what is on screen in each
~10-second window of footage, so an agent can choose a clip by what a line
is about.unspoken lets the render itself testify to words nobody said.reframe-detect), a review sheet, and stacked splits for two
speakers. Cards are redrawn at the new frame size, never stretched.events) that a crop, a sound or a
speed change can hang off, a clip inset into the recording, and a retime
for the slow parts..kdenlive or OTIO file and
finish anywhere.
Tell an agent what film you want. In Claude Code, install the plugin and describe the film: which recording is the voice, what the b-roll is, where the music goes, what it ends on. The agent imports, transcribes, cuts the retakes, hangs footage off the lines it belongs to, scores, masters and checks the render, using proofcut's tools and nothing else. It can look at the picture track as a labelled grid while it works, so it sees what it placed rather than a filename. Every MCP client runs the same server; the plugin is the one that needs no setup.
Cut from a shell, by naming words. Every tool is also a proofcut
subcommand printing JSON, so a cut is a script you can read, re-run and
diff. --plan prints what a range says before anything changes, and undo
walks it back.
Edit by hand in the workspace. Strike words in the transcript, drag-trim and razor on the timeline, review every crop in place, and export from Finish. It plays the source through the edit, so seeing a cut costs no render, and the truth strip warns while you edit if the film would ship wrong. The agent sits in a side rail of the same window.
Finish elsewhere, and still prove the file. Rough-cut here, export a
.kdenlive or OpenTimelineIO file, finish in Kdenlive, Resolve or Premiere,
and bring the trim back with import-edit. Then point verify at the
delivered file, and a retake left in is caught before anyone watches.
Cut a vertical teaser from the film. reel copies a span of the finished
film into a second project at another canvas, so the film itself is never
reshaped to take one render. It names every picture the teaser will not
have and pins the ones it keeps to the frames the film showed, so the
teaser shows what the film showed. Frame mode then reviews each crop on
the source's own frames.
Split a pile of recordings into shorts. Seed every recording as one
timeline, cut the retakes once, then split it by first and last word. Each
short becomes its own project beside the pile, holding only the recordings
it uses, and any stretch no short took is named rather than lost.
The first three are walked in § Try it; the reel, the split and the round-trip are in the manual.

verify, frames and hold check report is measured off the
delivered file, because a project can say captions are burned, or a line
is in, about a file that has neither.--plan to show
what they would do first, anything addressed by word echoes the words it
resolved to, and undo --steps N walks back an agent's whole turn.Nothing below installs anything until you say so, and every step prints what it would do first. § What it puts on your machine is the whole footprint and how to reverse it.
Check your machine, before cloning anything. proofcut doctor probes every
tool proofcut uses and prints the fix for anything missing
(§ Requirements has the list). It only looks. It installs
nothing and writes nothing. With uv installed:
That first run downloads Python 3.13 if uv has none, plus proofcut's
dependencies. That is about 230 MB, all of it inside uv's own cache, which
uv cache clean empties.
Then read what an install would do. On Linux, Windows and a Mac of either
kind,
proofcut setup --plan prints every piece it would fetch, its size, and which
doctor row asked for it, then stops without touching anything:
That is a bare machine. Yours will be shorter, because setup installs nothing doctor passed, so a working ffmpeg or melt of your own is never touched. With an NVIDIA GPU the whisper row is CUDA torch and the total is about 5.8 GB.
Drop --plan to go ahead. It reprints the plan, asks once, and installs for
you alone, with no sudo or administrator rights; proofcut setup --uninstall
removes exactly what it added, and nothing you already had.
The demo and your own recordings run from a checkout:
No footage needed. docs/DEMO.md makes a voiceover with a real retake, b-roll and a score, then walks a whole small film: cut the retake by naming its words, hang b-roll off a phrase, lay the score under the voice, render and master it, end on a card, and check the render against the timeline.
The plugin registers proofcut's MCP server, so every tool is available with no setup of your own:
The first start downloads about 175 MB of Python dependencies, and Claude
Code gives a server 30 seconds to connect. On a slow connection, start that
first session as MCP_TIMEOUT=300000 claude, or reconnect proofcut in /mcp
once the download has finished.
Any other MCP client runs the same server, from a checkout or with no checkout at all:
To watch the edit instead, open the workspace:
proofcut is 0.x software. A project from an older version is refused rather
than guessed at, and proofcut migrate brings it forward.
proofcut is a local tool that needs real media binaries, so proofcut setup
does download a few hundred megabytes. Here is all of it, where it goes, and
what takes it away. Sizes are a Linux x86_64 bare machine; proofcut setup --plan prints yours.
| What | Where | Size | Removed by |
|---|---|---|---|
| ffmpeg, ffprobe | setup's folder, with symlinks in ~/.local/bin | 126 MB | proofcut setup --uninstall |
| auto-editor | setup's folder | 46 MB | proofcut setup --uninstall |
| melt (Shotcut's portable build) | setup's folder | 155 MB | proofcut setup --uninstall |
| whisper | a uv tool, plus the Python 3.12 uv fetches for it | 1.9 GB, or 5.5 GB with an NVIDIA GPU | proofcut setup --uninstall |
| proofcut and its Python dependencies | uv's cache | 230 MB | uv cache clean, uv tool uninstall proofcut |
| the demo's media | the directory you name it | under 2 MB | delete that directory |
| the model store: what whisper, the vision model and the face detector said about each source | ~/.local/share/proofcut/store, beside setup's folder | tens of MB a year of shoots | proofcut setup --clear, or --uninstall |
"Setup's folder" is one directory: ~/.local/share/proofcut/deps
($XDG_DATA_HOME if you set it), or %LOCALAPPDATA%\proofcut\deps on
Windows. It holds everything except whisper, which is a uv tool because that is
how whisper ships.
Five rules it holds to, each one enforced by a test rather than promised here:
--plan writes nothing at all, and its exit code reports only what is
missing (test_setup_plan_writes_nothing_and_exits_by_what_is_missing), so
reading the plan can never turn into performing it.latest tag. A hash that does not match leaves nothing
behind.--uninstall
removes exactly those, including the Python uv fetched for whisper.
tests/test_install.py installs the lot into a fake home, uninstalls, and
asserts the home's listing is what it was before
(test_install_then_uninstall_leaves_the_home_as_it_was), so "removes
exactly what it added" is checked on every run of the suite, not just meant.
A link you repointed yourself is left alone, because it is yours now.To see a removal before it happens:
Two things setup deliberately does not do: it is a command you type and never an MCP tool, so an agent cannot start a 2 GB download or change your PATH; and it touches nothing outside your own user account.
GitHub's macOS and Windows runners take the demo to a checked render, but a runner never reads the instructions. On a Mac, one person has taken the demo to a checked render, on an Intel Mac (i7-8850H, macOS 15.7.9); on Apple silicon only the runner has. On Windows, the author's own Windows 11 laptop has, twice, and nobody else's PC; Windows 10 and ARM64 PCs have not been tried at all. If you have one of these machines and half an hour, one script installs what proofcut needs, makes a short test video, has proofcut cut, score, master and check it, and puts a report on your Desktop. It asks before it starts, records what it added, and removes exactly that on request, nothing you already had. A run that stops at the first step is just as useful, because where it stops is the finding.
On a Mac:
It downloads uv into ~/proofcut-mac-trial and uses it to run
proofcut setup, which fetches whatever of ffmpeg, auto-editor, Shotcut's
renderer and whisper your Mac is missing (§ What it puts on your
machine). It asks for no password; an Intel
Mac needs Apple's Command Line Tools, and the script says so if they are
missing. bash proofcut/scripts/mac_trial.sh --uninstall runs proofcut setup --uninstall and deletes that folder.
Then file the report.
On Windows, from PowerShell:
It downloads uv into one folder under %LOCALAPPDATA% and uses it to run
proofcut setup, which fetches whatever of ffmpeg, auto-editor, Shotcut's
renderer and whisper your PC is missing. Nothing is installed system-wide
and it needs no administrator rights. The same command with -Uninstall
runs proofcut setup --uninstall and deletes that folder. It puts proofcut-windows-report.zip on
your Desktop with your home folder's name taken out; file the report.
proofcut is developed on Linux (a Fedora-based desktop). On macOS and Windows the test suite passes on CI; where each OS stands by hand is § Help wanted above, and in detail docs/plans/PORTABILITY.md.
Every hard part of an editor already exists as mature open source, and
proofcut is the layer that lets an agent drive those tools and check what
they produced. Run uv run proofcut doctor to check everything below at
once. On Linux, Windows and a Mac of either kind, uv run proofcut setup installs
any of the last four that doctor marks ✗
(§ What it puts on your machine, and
--plan to read it first): a static ffmpeg, whisper,
auto-editor's release binary and Shotcut's melt (on Linux the portable
build, which renders with no display at all;
docs/plans/INSTALL.md).
| You need | For | Notes |
|---|---|---|
| Python 3.13 and uv | everything | uv sync installs the Python side. The only runtime dependencies are mcp and OpenTimelineIO, which holds the timeline and exports it to other editors. |
ffmpeg / ffprobe built with libx264, freetype and libass | cutting, concatenating, captions, rendering | Fedora's default ffmpeg-free has no libx264: use RPM Fusion's ffmpeg. On a Mac, Homebrew's ffmpeg lacks freetype and libass: install ffmpeg-full and put $(brew --prefix ffmpeg-full)/bin first on PATH (it is keg-only). |
| auto-editor 31+ | silence and bad-take removal, single-source renders | Install the upstream binary. The PyPI package is a stale 29.x. |
| whisper | word-timed transcription (30+ languages), render verification | Any openai-whisper install. uv tool install --python 3.12 openai-whisper is the short route (3.12 because torch's Intel-Mac builds stop there, and on an Intel Mac also --with 'numpy<2', which that last torch needs); add --torch-backend cpu without an NVIDIA GPU (1.9 GB instead of 5.5 GB). Found via PROOFCUT_WHISPER, then PATH. The CPU build transcribed the demo's 19-second voiceover in 33 seconds. |
MLT (melt) | layered renders (b-roll, cards, music) | Your distribution's MLT package (mlt on Fedora, whose melt package is an unrelated compression tool), or Kdenlive, whose flatpak copy is found automatically. PROOFCUT_MELT overrides both. |
Optional. Each unlocks one feature, proofcut doctor reports whether it is
available, and everything else works without it:
| Optional | Unlocks | Notes |
|---|---|---|
ImageMagick 7 (magick) | title and end cards, rendered from SVG templates | ImageMagick 6's convert is not used, so distributions that still ship 6 (Ubuntu 24.04) need ImageMagick's own build. |
Claude Code (claude, logged in) | the agent pane in the workspace | proofcut mcp works with any MCP client; only the pane runs claude itself. |
PROOFCUT_VLM | describe (b-roll search by what's on screen) | The python of a venv with torch, transformers, bitsandbytes and Pillow, on a CUDA GPU. The Qwen2.5-VL model downloads on first use. |
PROOFCUT_FACE | reframe-detect (face-aware crops) | The python of a venv with insightface, onnxruntime and opencv-python. |
PROOFCUT_TTS, PROOFCUT_TTS_MODEL, PROOFCUT_TTS_VOICE | vo-synth (a line in a cloned voice) | A python with qwen-tts and a CUDA torch, a local Qwen3-TTS snapshot, and a directory holding a reference clip of the voice. There is no default voice, on purpose. |
Whether you're a person or a coding agent, start with CLAUDE.md. It holds the rules and the traps this repo has already hit, and Claude Code loads it automatically. CONTRIBUTING.md is the short version a pull request is checked against, and SECURITY.md says how to report a vulnerability.
Where things live:
| Path | What it is |
|---|---|
src/proofcut/ops.py | Every operation. The MCP tools, the CLI and the web UI all call these. |
src/proofcut/server.py | The MCP server. Register tools with @_tool(), never @mcp.tool(). |
src/proofcut/cli.py | The proofcut command: one subcommand per tool, printing JSON. |
src/proofcut/webui.py, src/proofcut/web/ | The workspace. It posts to ops and renders what comes back; it never decides anything itself. |
src/proofcut/project.py, timeline.py | The project manifest (proofcut.json) and the OTIO timeline. |
tests/ | test_server_stdio.py drives a real proofcut mcp subprocess; test_webui_http.py a real socket. |
scripts/ | The demo maker, the Mac and Windows trial kits, screenshot capture. |
docs/ | The manual, the demo, and the design record (below). |
Run the checks:
The suite talks to a real proofcut mcp subprocess, so it is slower than a
pure unit suite. Tests that need whisper, auto-editor, melt or ImageMagick
skip when the tool is missing. Tests that render through melt also need a
display: on a headless machine use QT_QPA_PLATFORM=offscreen or xvfb-run -a (proofcut doctor tells you which your MLT needs). Without one they fail
with "no display for MLT's Qt module to open", which is the environment, not a
regression.
The documentation:
proofcut's reasoning is part of what it ships, so the design record is public:
PolyForm Shield 1.0.0. proofcut is source-available, not open source: you can read, run, change and redistribute it for any purpose except building a product that competes with it. Cutting your own videos, running it for clients, building on it and forking it to fix a bug are all fine. For a commercial licence, ask.
The bundled typefaces are not proofcut's to relicense. The caption face in
src/proofcut/fonts/ and the three browser faces in src/proofcut/web/ are
OFL-1.1, each with its licence text beside it and its source in that
directory's FONTS.md.
If proofcut cut a video for you, you can buy me a coffee on Ko-fi.