WeCut

WeCut

[CI] [npm] [License]

WeCut is a free, open-source video editing engine for AI agents. The agent writes a small JSON project; wecut renders it with the FFmpeg already on the machine. It cuts, captions, reframes and mixes short-form video, and it can analyse a video that went viral and reuse its format as a template on new footage. CLI and MCP server. No cloud, no API key, no GPU, no telemetry.

Things you can ask an agent that has WeCut:

• "Cut this 40-minute podcast into five vertical clips with karaoke captions."
• "Add word-by-word captions to talk.mp4 and put the music under it, quieter when he speaks."
• "This TikTok went viral. Work out why and make the same kind of video from my footage."
• "Turn these 8 photos into a 9:16 slideshow on the beat with a title."
• "Save this edit as a template so we can do the same every week."

npx -y wecut doctor                           # is FFmpeg ready?npx -y wecut guide                            # the full guide for agentsnpx -y wecut probe media/talk.mp4             # duration, size, fps, audionpx -y wecut validate project.json            # errors with JSON pointers and fix hintsnpx -y wecut preview project.json --at 1,5,9  # small JPG frames to look atnpx -y wecut render project.json              # out/clip.mp4npx -y wecut mcp                              # the same, as an MCP server on stdio

Every command prints one JSON object on stdout. Exit codes: 0 ok, 2 invalid input, 3 missing dependency, 4 render failed, 5 over a limit.

Visual editor for humans

WeCut Studio is an independent static web editor. Choose local clips, trim and reorder them, add text and music, then download a portable template for an agent on another device. Editing runs in the browser; rendering runs on the agent's computer. A public editor needs only static file hosting, not a rendering server. A localhost URL itself is not public.

Run python -m http.server 8770 --bind 127.0.0.1 --directory studio from this checkout and open http://127.0.0.1:8770. No build or backend is needed. The template file is shared through your agent chat; public template storage and project autosave are not included. Bundle import requires the 0.2.0 source/build; published npm 0.1.0 does not include it yet.

Install in your agent

The quick way, for Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, Windsurf and Grok Build:

npx -y wecut setup           # shows what it would changenpx -y wecut setup --apply   # registers the MCP server and the skill, backs up each file it editsnpx -y wecut setup --remove --apply

It only touches the clients it finds (or --client codex,cursor), keeps every other setting as it was, and reads each file back. Quit Claude Desktop before you run it: while it runs it can write its settings back and drop the entry. Run it again after updating WeCut, so the installed skill stays current. Or do it by hand:

WeCut needs FFmpeg 6 or newer with libass (npx -y wecut doctor checks it and says what to install):

• Debian/Ubuntu: sudo apt-get install -y ffmpeg
• macOS: brew install ffmpeg-full (the slim ffmpeg formula has no libass; WeCut finds ffmpeg-full on its own)
• Windows: winget install Gyan.FFmpeg

Then connect it to the agent you use. The MCP server works in a fixed workspace folder (--root, default: the folder it was started in); every media path is relative to it.

Claude Code

claude mcp add wecut -- npx -y wecut mcp

Or as a plugin, which also installs the WeCut skill:

/plugin marketplace add 13kailouis-stack/wecut/plugin install wecut@wecut

Any MCP client

Claude Desktop, Cursor, Windsurf, Cline, Roo Code, LM Studio and most other clients take this block in their MCP settings file. Give --root explicitly, because desktop apps start servers from an unpredictable folder.

{  "mcpServers": {    "wecut": { "command": "npx", "args": ["-y", "wecut", "mcp", "--root", "/path/to/workspace"] }  }}

[Add to Cursor]

VS Code (Copilot agent mode)

code --add-mcp '{"name":"wecut","command":"npx","args":["-y","wecut","mcp"]}'

or in .vscode/mcp.json:

{ "servers": { "wecut": { "type": "stdio", "command": "npx", "args": ["-y", "wecut", "mcp"] } } }

OpenAI Codex CLI

codex mcp add wecut -- npx -y wecut mcp

or in ~/.codex/config.toml:

[mcp_servers.wecut]command = "npx"args = ["-y", "wecut", "mcp"]

Gemini CLI

gemini extensions install https://github.com/13kailouis-stack/wecut

Agents with a terminal

WeCut targets any agent with permission to run local programs and access the user's media. Product names do not determine compatibility: a terminal agent can use the CLI without MCP.

Grok Bot, Manus, Muse, OpenBot, Dots and Claude Duet are examples of requested integration targets, not a list of tested integrations. For each product, verify that its execution environment can run the WeCut binary and FFmpeg. A chat interface alone does not provide that access.

npx -y wecut guide     # read this first: workflow, project format, templatesnpx -y wecut doctor

Then follow the guide: probe, write project.json, validate, preview, render. In a fresh Linux sandbox install FFmpeg first with sudo apt-get install -y ffmpeg.

Clients that can launch a local MCP process can use wecut mcp over stdio; the client-specific examples above are not an allowlist. An HTTP-only MCP client needs a separate bridge: WeCut does not currently serve remote HTTP MCP. Browser-only agents need an execution environment before they can render. Node is needed for the npm launcher; a standalone binary does not need Node.

Agent Skill

The skill in skills/wecut/SKILL.md teaches the workflow to agents that load skills (Claude Code, Claude apps, Codex, Cursor and others):

npx skills add 13kailouis-stack/wecut

Other ways to get the binary

• npm (Node 16+): npx -y wecut <command>, or npm i -g wecut. npm installs only the binary for your platform (@wefluence/wecut-<os>-<arch>); there are no install scripts.
• Binary: download the archive for your OS from GitHub Releases and check it against SHA256SUMS.
• Source (Go 1.22+): go build -o wecut ./cmd/wecut

Prebuilt for Linux, macOS and Windows on x64 and arm64. Set WECUT_BINARY to use your own build through the npm launcher.

What it does

• Cut, join and speed up clips (0.25x to 4x), with 9:16, 16:9, 1:1, 4:5 and other canvases
• Cover crop with a focus point and zoom, or contain on a colour or blurred background
• Photos with Ken Burns motion
• 36 transitions (FFmpeg xfade), clip fades
• Text with 31 styles (news cards and labels, bubble, fire, Bebas titles, Kanit caps, elegant serif, script...), 40 bundled fonts (Poppins from Medium to Black with real italics, Kanit, Bebas Neue, Luckiest Guy, Creepster, Abril Fatface, Great Vibes and more), 18 caption styles, emphasised words in another colour, pop / type / slide / fade animations
• Colour fades over the footage and under the text (gradients), like the dark fade behind captions
• Footage in a card on a plain or grid background with rounded corners (inset), colour washes for a stretch of the video, captions that light up word by word (reveal) with key words set apart (accent)
• Captions from a transcript: phrase, karaoke (spoken word highlighted) or one word at a time. Transcript times can stay in source-file seconds; WeCut maps them through the cuts
• Image overlays (logos, stickers) with opacity, rotation and fades
• Music and sound effects with trim, loop, fades and automatic ducking under speech. Renders are loudness-normalised toward −14 LUFS (--no-loudnorm skips it)
• Colour filters and effects (flash, cinema bars, frame, dim, night, sepia)
• Analysis of an existing video: shots, pace, hook length, flashes, tempo and beat sync, pauses, platform outro, and a frame sheet the model can look at
• Templates ("recipes"): the shape of an edit, applied to new clips, words and music; save your own from any project
• MP4 (H.264 + AAC, faststart) or GIF output

Clone a video into a template

wecut clone media/viral.mp4 --name news-card   # -> recipes/news-card.json + out/clone/news-card/compare.jpg

clone turns a finished video into a template the way an editor would have built it: every cut and transition (flash, fade, dissolve, zoom, blur) at its exact time, each shot's framing (full screen, or shown whole on black or blurred bars) and push-in, the text cards with their colours, box, size, line spacing, padding, timing and entrance (fade, pop, slide or type), the caption style and position, the logo, and a talk that already plays under the opening B-roll. A steady beat is stored as beat indexes; recipe apply snaps those cuts onto replacement music. Each shot is a media slot, like a CapCut template. WeCut holds no model and no API key: it returns a review with the images and evidence behind each finding, and the agent running it looks and answers, so words, fonts, what each shot is and the kind of each transition come from real eyes and OCR is only a fallback. The comparison sheet puts the original beside the template filled with numbered stand-ins, so a person or a model can check it at a glance. People fill the slots in WeCut Studio; agents with wecut recipe apply. Details and the format: docs/clone.md. Cloning needs the 0.3.0 source/build; the published npm 0.1.0 does not have it yet.

Analyse a video, reuse its format

wecut analyze media/viral.mp4                 # shots, pace, hook, flashes, tempo, pauses + a frame sheetwecut recipe list                             # templates: built-in and the workspace's recipes/*.jsonwecut recipe apply --input request.json       # recipe + new clips, words, music -> projectwecut recipe from-project my-edit.json --write recipes/my-style.json   # "save as template"

analyze measures what a model cannot see in a transcript: where the cuts are (a white flash or a strobe counts once), how long the opening shot holds, whether cuts land on the beat, and whether the file ends with a silent platform outro. Its frame sheet, one frame per shot with timestamps, is how the agent reads the headline card, text style and framing.

A recipe (wecut.recipe/1, schema in schema/wecut.recipe.schema.json) is an edit's shape without its content: sections fed by roles (a 5 s hook with a headline card, then the body), text slots filled at apply time (with emphasis for the words to colour), caption and music style, effects on cuts. A recipe can carry its own default track, like a CapCut template; the music passed at apply time replaces it and "none" drops it. The built-in recipes copy the structure of formats that are common on Indonesian short-form video today: news-style reposts with a headline card, quote hooks, phrase-captioned vlogs, punched-in podcasts, photo slideshows.

Copy the structure, not the content: other creators' footage, wording and music stay theirs.

MCP tools and prompts

Prompts (slash commands in clients that show them): clips-from-video, copy-viral-format, add-captions, save-template.

Projects go in as an object (project) or a workspace file (projectFile). The server speaks both protocol eras: modern clients (2026-07-28, per-request _meta, server/discover) and clients that open with initialize (2024-11-05 to 2025-11-25). Renders run one at a time; notifications/cancelled stops one and removes its partial file.

Project format

wecut guide (the same text as skills/wecut/SKILL.md) explains the workflow, the two clocks (source seconds vs output seconds), captions and troubleshooting. wecut schema prints the full JSON Schema and wecut example <name> prints a working project.

{  "wecut": "1",  "output": { "file": "out/clip-01.mp4", "ratio": "9:16" },  "clips": [ { "src": "media/talk.mp4", "from": 754.2, "to": 781.0, "focus": { "x": 0.42, "y": 0.5 } } ],  "texts": [ { "text": "How I made my first $10k", "end": 3, "style": "hook", "y": 0.2, "in": { "type": "pop" } } ],  "captions": { "words": "media/talk.words.json", "src": "media/talk.mp4", "style": "karaoke" },  "audio": [ { "src": "media/music.mp3", "volume": 25, "loop": true, "duck": true } ]}

FAQ

What is WeCut? An open-source command-line video editor made for AI agents. The agent describes an edit as JSON, WeCut checks it, shows preview frames and renders it with FFmpeg on the same machine. It is made by Wefluence, an Indonesian UGC and clipping marketplace.

Is it free? Yes. Apache-2.0, no account, no API key, no usage limits. It runs on your own computer or your agent's sandbox, so there is no server bill either.

How do I let ChatGPT, Claude, Grok or another AI edit videos? Give the agent WeCut: as an MCP server (npx -y wecut mcp) in clients that support MCP, as the skill, or by letting an agent with a terminal run npx -y wecut guide and follow it. See Install in your agent. Chat apps without a code sandbox cannot reach files on your computer; use a desktop or terminal agent for those.

Can an AI agent make TikTok, Reels or YouTube Shorts from a long video? Yes. The agent reads a transcript, picks the moments, writes one project per clip with captions.src pointing at the source, previews one, and renders them all in 9:16 with captions.

Can it copy the format of a viral video? It measures the video (wecut analyze: cuts, pace, hook length, flashes, tempo, pauses, outro) and returns a frame sheet the model looks at. The agent then picks or writes a recipe and applies it to new footage, words and music. It copies the structure, not the footage, wording or music.

Does it transcribe speech? It reads word timings from OpenAI or Groq Whisper verbose_json, whisper.cpp JSON, SRT, VTT or a plain word list. wecut transcribe media/talk.mp4 writes those timings locally: FFmpeg's whisper filter when this build has it, otherwise a whisper-cli (or whisper-cpp / whisper) binary on PATH. Both need a ggml model (--model, WECUT_WHISPER_MODEL, or models/ggml-base.bin). Nothing is downloaded. wecut doctor reports local_transcription: true when either engine is available.

Does it upload my video anywhere? No. WeCut makes no network requests and has no telemetry. Media paths are refused if they are URLs or outside the workspace.

Does it need a GPU? No. It encodes with libx264 on the CPU by default and can use NVENC, Quick Sync or VideoToolbox with --encoder. A 43-second 1080x1920 clip with captions renders in about 28 seconds on a 2019 laptop.

Which platforms? Linux, macOS and Windows on x64 and arm64, with FFmpeg 6+ and libass.

Can I make my own templates? Yes. An agent can write and revise project JSON from your instructions, validate it, preview it and render it. You do not have to edit manually first. Then run wecut recipe from-project my-edit.json --write recipes/my-style.json, or author recipe JSON directly using wecut recipe schema. Workspace recipes appear in wecut recipe list beside the built-ins.

A recipe can retain a music path, but does not bundle the audio file. Extraction captures a reusable structure rather than a lossless copy of every project feature. Review the applied recipe before reusing it in bulk.

The Wefluence Creator companion adds Kirim ke agent to a saved project's menu: export a recipe with music, then send it to an agent on another device. In the 0.2.0 source/build, wecut recipe unpack received.wecut.json --write templates/my-style imports it; recipe pack creates a package from an engine recipe. Published npm 0.1.0 does not have these commands. See cross-device template authoring for supported edits, limits and rollout requirements. Visual import back into the app is not implemented.

Compared with other ways to edit video from an agent

Safety

WeCut runs on someone else's machine and takes instructions from a model that may have read hostile content. So:

• FFmpeg is started with an argument list, never through a shell.
• Text never enters the FFmpeg filter graph. All text goes through an .ass file with braces and backslashes escaped, so a caption cannot inject override tags or filters.
• Every input and output must be inside the workspace (--root, default: current folder). .., absolute paths outside it, symlinks pointing out, and URLs are refused. Output may not overwrite an input.
• Inputs are opened with -protocol_whitelist file and a demuxer whitelist (MP4/MOV, Matroska/WebM, common audio and image formats). HLS playlists, concat lists and network protocols are refused, including a playlist renamed to .mp4.
• Limits: 10 minutes of output, 4K, 100 clips; renders time out (default scales with length).
• Renders are written to a temporary name, checked with ffprobe (size, duration, audio), and only then moved into place.
• No telemetry. WeCut makes no network requests.

Speed

Measured on a 2019 laptop (Intel i5-1035G7, 4 cores, under load), final preset, 1080x1920 unless noted:

Encoding dominates; text and captions cost almost nothing. A plain cut without re-encoding is not used, because any crop, caption or effect needs a re-encode.

Project layout

cmd/wecut          entry point (CLI and `wecut mcp`)internal/spec      project format: types, strict decoding, validation, cataloginternal/engine    timeline, captions, .ass builder, FFmpeg graph compiler (pure, no I/O)internal/analyze   shots, pace, tempo, pauses from FFmpeg's measurements (pure)internal/recipe    the template format: validate, apply to new material, derive from a projectinternal/ff        finding, probing and running FFmpeginternal/cli       the commands; every result is one JSON objectinternal/mcp       MCP stdio server, a thin layer over internal/cliinternal/workspace keeps every path inside the workspaceinternal/assets    fonts embedded in the binaryschema/            JSON Schema (kept in sync with the Go types by a test)examples/          example projects (`wecut example`)recipes/           built-in recipesskills/wecut/      Agent Skill (`wecut guide` prints it)npm/wecut/         the npm launcher (`npx wecut`)tools/release/     builds all platforms, npm packages and release archives into dist/

Agent and registry manifests: server.json (MCP Registry), .claude-plugin/ (Claude Code plugin and marketplace), gemini-extension.json and GEMINI.md (Gemini CLI), glama.json, llms.txt, AGENTS.md (for agents changing this code).

Release build: go run ./tools/release -version 0.2.0 (nothing is published; see .github/workflows/release.yml).

Tests: go test ./... (the CLI tests render real video and are skipped without FFmpeg). Golden FFmpeg plans live in internal/engine/testdata; after an intended change run go test ./internal/engine -update and render the examples to check them.

Roadmap

• uvx wecut (PyPI wheels) and an MCPB bundle for one-click install in Claude Desktop
• Video overlays (picture-in-picture), stickers, more effects
• Optional Wefluence bridge for paid clipping campaigns (separate package)

License

Code: Apache License 2.0 (see LICENSE). Bundled fonts: SIL Open Font License 1.1 or Apache 2.0, see internal/assets/fonts/LICENSES.md.