framely

AI-native video editor — a CLI (+ MCP server) that AI agents operate. framely ships the tool, not the brain: the calling agent (Claude Code, any MCP host) is the intelligence; framely gives it a typed, safe, undoable video-project surface. All render/analysis runs on your machine (headless Chrome + WebCodecs) — no media leaves it except the audio slice you explicitly send to hosted captions.

The npm package is framely-cli; it installs the framely command.

Install

npm i -g framely-cli      # installs the `framely` command

Requirements: Node ≥ 22 and Google Chrome installed (used headless for analyze/render; macOS + Linux first-class, Windows best-effort). Nothing else to download.

Use with Claude Code (MCP)

framely's primary surface is an MCP server — the agent is the brain, framely is the typed hand:

claude mcp add framely -- framely mcp                       # current directory is the project
claude mcp add framely -- framely mcp --project /path/to/proj

Tools exposed: ops_schema, init_project, add_asset, get_project, apply_ops (atomic, undoable; {dryRun:true} previews), undo/redo, get_facts, analyze, cut_silences, captions_build, transcribe, render. Invalid ops come back as typed, retryable tool errors — nothing is persisted on failure. There is no LLM inside framely.

Quick start (CLI)

framely init demo
framely add clip.mp4                     # auto-probes duration/kind
framely ops --schema                     # the op contract an agent reads
echo '[{"op":"addClip","assetId":"<id>","startSec":0,"durationSec":10}]' | framely apply -
framely cut-silences                     # the marquee: analyze silence → cut → close gaps
framely render -o out.mp4                # proof, on your machine
framely show
framely undo
sudo npm i -g framely-cli && framely bridge   # global install (needs admin) — or `npx framely-cli@latest bridge` (no install)

framely bridge — URL import for the web editor

The web editor (framely.video) can't download a YouTube URL itself — a Cloudflare Worker's datacenter IP is bot-blocked by YouTube, and the browser can't read cross-origin media. framely bridge runs a small HTTP loopback server on http://127.0.0.1:47700 (IPv4 + IPv6). The web page reaches it via Chrome 142+ Local Network Access (targetAddressSpace:"loopback"), which exempts the loopback literal from mixed-content and prompts to allow local-network access. Extraction is self-contained: it pulls YouTube formats with bundled youtubei.js from your own IP and merges video+audio with mediabunny (no yt-dlp, no ffmpeg); the web editor fetches from it (CORS-granted to framely.video only). So the download happens entirely on your machine — nothing goes through framely's servers, and you install nothing beyond the CLI. framely bridge installs a background service (macOS launchd / Linux systemd) that auto-starts on login and returns to the prompt — run it once. framely bridge --stop removes it; --status checks it; --run runs in the foreground. Then in the editor: File → Import from URL (Chrome may ask to allow local-network access — click Allow).

A project is project.json + an append-only event log at .framely/log.jsonl (undo = replay). Entity ids are assigned once, at apply time, and stay stable across later commands (deterministic replay).

Run framely --help (or framely <verb> --help) for the full verb list and flags. Design SSOT and exploration log live in the repository.