kimo
Summary: kimo is an MCP video-editing engine exposing 14 grouped tool families (plus discovery helpers) that let an AI agent build, edit, grade, animate, and export video projects.
Project management (
project, 35 actions): import media, save/load, project settings, undo/redo, inspect state.Timeline editing (
timeline, 37 actions): add/move/trim/split clips, ripple/roll/slip/slide, speed changes, markers, multicam, silence removal.Animation (
animate, 32 actions): keyframes, curves, expressions, motion paths/presets, camera, blending, corner/mesh pins.Effects & transitions (
effects, 15) and masks/roto/keying (masks, 16).Text (
text, 23): titles, captions, subtitles, SRT, fonts, transcription, text animators.Graphics (
graphics, 20): shapes, bezier paths, modifiers, layer styles, HUD frames, counters, detection boxes.3D/VFX (
vfx3d, 15): scenes, lights, materials, relight, particles, shard/fracture effects.Tracking (
tracking, 25): point/planar/mesh/feature tracking, stabilization, camera solve, lens undistort.Color (
color_grade22,color_science18,scopes12): primaries, curves, wheels, node graphs, LUTs, CDL, ACES/OCIO/HDR, waveform/vectorscope and exposure analysis.Audio (
audio, 17): levels, effects, pan, ducking, loudness normalization, beat detection, audio export.Output (
output, 40): render frames, export video/GIF/alpha, presets, EXR/TIFF, LUTs, camera solves.Discovery helpers:
search_tools,kimo_describe, andkimo_enable_groupto find tools, inspect schemas, and list a group's tools individually.
Uses ffmpeg and ffprobe as the media backend for the editor: all decoding, encoding and media probing of imported assets and exported timelines go through them. This lets the server ingest arbitrary video/audio source files as editable clips and write out rendered frames, video exports, GIFs and EXR sequences without a bundled codec stack.
kimo
The video editor your AI drives.
A real desktop video editor with an engine where every cut, keyframe, grade and export is a tool call. Bring Claude Code, Codex or Antigravity on the plan you already pay for, and watch every edit land on the timeline.
Made with kimo. A 33-second brand reveal, rendered by the engine from tool calls an agent made. Watch with sound ▶
Download · What's new in 9 · Connect your AI · What it can do · Gallery · How it works · Docs
“Cut out the silences, add a title and captions, grade it warm, and export a 9:16 short.”
Type that into kimo's Agent tab. Your agent plans it, calls the engine tool by tool, and every change appears on the timeline as it happens, each with its own Undo. Take over by hand at any moment: it is one project, one history.
✦ Why kimo
🤖 AI-native
Every feature is a registered engine command, and the MCP tool list is generated from that same registry. Whatever you can do in the editor, your agent can do too, on the same project.
💳 Your plan, not ours
kimo runs the official Claude Code, Codex or Antigravity CLI you are already signed in to. No new subscription, no API key needed, and kimo never sees your password or tokens.
👀 Watch every edit
The Live view shows each agent action as it lands, who made it, what the engine thought of it, and a one-click Undo. Several agents can share the open project at once.
🎬 The whole stack
Editing, motion graphics, text and captions, VFX, tracking, 3D and pro color: the reach of CapCut, Premiere, After Effects and Resolve, in one engine.
⚡ Runs anywhere
A CPU renderer tuned for a 2 GB machine, no GPU needed. The same engine runs headless on a laptop, a server or in CI.
📏 Measured, not claimed
Every "better than X" line in FEATURES.md has a stated baseline and a measured number, losses included. Open source under MIT.
Related MCP server: mcp-screenshot
✦ What's new in kimo 9
kimo 9 is the first release where the desktop app is the product: one download with the editor, the engine and your agents in one window.
The app
🎞️ A real editor. Media bin with drag-and-drop, viewer, inspector, a timeline with move, trim, split, snap and markers, and export with progress.
▶️ Real-time preview with sound. Plays ahead of the playhead with synced audio. J/K/L shuttle, loop and full screen.
🐢➡️⚡ Background proxies. Heavy 4K or long-GOP imports return at once; light edit proxies build in the background.
🧠 Your agents, your plan. Claude Code, Codex and Antigravity with model and effort pickers, streamed steps, Stop and resume.
The engine
👁️ Engine eyes. Every edit is observed: before and after frames, measured, and judged by critics (black gaps, unreadable text, jitter, clipped highlights), each finding with its fix.
🧩 Asset creation. SVGs as animatable layers, CSV-driven animated charts, a searchable library of openly licensed icons and figures, Indian number grouping (1,00,000).
🪟 Windows-solid. Long exports, code clips and audio on hour-long edits fixed on Windows; an untouched clip exports by stream copy in seconds.
Safe by design
💾 Autosave and crash recovery | Your project is saved in the background. After a crash, kimo offers it back on the next start, with its undo history, so Ctrl+Z still works. |
🔄 Signed in-app updates | kimo checks GitHub releases and shows Update to x.y.z. Nothing installs until you click; every update is verified against kimo's signing key first. |
🩹 Opt-in crash reports | A crash writes a log on your computer. Next time kimo asks whether to send it, and you review and submit it yourself. Nothing is sent otherwise. |
Full list in CHANGELOG.md. Details: updates and crash reports.
✦ Get kimo
1. Download kimo 9 from the latest release or getkimo.tech:
System | File |
🪟 Windows 10/11 (64-bit) |
|
🐧 Linux x86_64 |
|
One app: a video editor with the kimo engine inside. Media bin, viewer, timeline, inspector and export, plus an Agent tab and a Live view.
2. Pick your agent, on the plan you already have. No API key needed: kimo runs the official CLI you are signed in to.
Agent | Plan | Install once |
Claude Code | Claude Pro or Max |
|
Codex | ChatGPT Plus, Pro, Business or Enterprise |
|
Antigravity | Google account |
The Connections tab finds them, shows whether each is signed in, and opens the CLI's own sign-in in a terminal when it is not. kimo never sees your password or tokens. An API key (OpenAI, Anthropic, Gemini, OpenRouter, Groq or any OpenAI-compatible server) still works for people without a plan.
3. Ask for an edit in the Agent tab, or in the bar under the viewer:
"Cut out the silences, add a title and captions, and export a 9:16 short."
Every step streams into the chat, every change lands on the timeline as it happens, and each one gets its own Undo.
Your own terminal or IDE too. Press Add kimo to Claude Code / Codex / Antigravity in Connections (or point any MCP app at kimo-gui mcp). While the app is open, those sessions join the project you are looking at; when it is closed they get their own engine.
kimo needs FFmpeg; it uses the copy already on your computer, or offers to download it on first start.
Installers are built by the release workflow on GitHub-hosted runners, with a SHA256SUMS file. CI installs each one, starts it, checks that the engine runs and that an agent can attach to the open app, then uninstalls it. Installers carry an updater signature (.sig) that the app checks before installing an update; they are not yet Authenticode code-signed on Windows. macOS is coming later.
Linux x86_64 | Windows x64 | |
kimo app (editor + engine) |
|
|
Engine only (CLI + MCP server) |
|
|
sha256sum -c SHA256SUMS --ignore-missing # Linux
Get-FileHash .\kimo-setup-windows-x64.exe -Algorithm SHA256 # Windows PowerShellLinux
sudo apt install ./kimo-linux-amd64.deb # remove with: sudo apt remove kimo
# or, no install:
chmod +x kimo-linux-x86_64.AppImage && ./kimo-linux-x86_64.AppImage # no FUSE? add --appimage-extract-and-runWindows. Run kimo-setup-windows-x64.exe (per user, no admin). SmartScreen says "Windows protected your PC": click More info, then Run anyway. It uses Microsoft Edge WebView2 (already on Windows 11).
1. Prerequisites
All platforms: the Rust toolchain from rustup, cmake and a C++ compiler (the engine builds vendored Manifold), and ffmpeg + ffprobe on PATH at runtime.
curl --proto '=https' --tlsv1.2 -sSf \
https://sh.rustup.rs | sh
sudo apt install build-essential cmake \
libssl-dev ffmpeg
# spectator app only:
sudo apt install libwebkit2gtk-4.1-dev \
libsoup-3.0-dev \
libayatana-appindicator3-dev \
librsvg2-devVisual Studio Build Tools with Desktop development with C++ (MSVC, Windows SDK, CMake).
rustup-init.exe (default
x86_64-pc-windows-msvc).WebView2 Runtime (already on Windows 11).
ffmpeg, for example
winget install Gyan.FFmpeg.
xcode-select --install
curl --proto '=https' --tlsv1.2 -sSf \
https://sh.rustup.rs | sh
brew install cmake ffmpeg
# spectator app only:
brew install nodeLinux x86_64 is the tested platform for the engine. The Windows list follows the Tauri and Rust prerequisites; the release workflow builds the engine and the spectator with it on a GitHub Windows runner, but a build from clone on a real Windows PC has not been tried yet.
Step 4 (the spectator app) also needs Node.js 18 or newer for npx; the CI jobs use Node 22.
macOS: no installer in this release, and it has not been built on a Mac here. The commands in the macOS column and in steps 2-4 are the same ones the Linux and Windows CI jobs run; crates/kimo-core/build.rs links libc++ on macOS. Reports welcome.
2. Build the engine
git clone https://github.com/naman-sharma12345/kimo.git
cd kimo
cargo build --release --workspace --bins # on a 2 GB box: CARGO_BUILD_JOBS=1 (cold build ~17 min)
target/release/kimo --version # the version in Cargo.toml and the git commitkimo-mcp is the MCP server (stdio). kimo is the command line client for the same tools.
3. Run it headless
kimo-mcp takes no required arguments: it reads JSON-RPC on stdin and writes replies on stdout. Your MCP client normally starts it for you.
target/release/kimo-mcp # headless MCP server; streams telemetry to the spectator when it is open
KIMO_SPECTATOR=off target/release/kimo-mcp # same, with telemetry off
target/release/kimo-mcp --spectator-demo # demo mode: one paced frame per call (needs the spectator open)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | target/release/kimo-mcp # quick checkThe check prints "serverInfo":{"commit":"...","name":"kimo",...,"version":"..."}. --demo-pace-ms <50..100> sets the demo pace; KIMO_TOOLS picks the tool list profile.
4. Build the kimo app
The app is its own Cargo workspace in crates/kimo-gui. For a quick run from the checkout (it finds the engine in target/release and the fonts in fonts/):
cd crates/kimo-gui
cargo build --release --features custom-protocol
./target/release/kimo-guiInstallers, with the engine inside as a sidecar and the fonts as resources (what the release workflow does):
cargo build --release -p kimo-mcp && bash fonts/fetch.sh # from the repo root
mkdir -p crates/kimo-gui/binaries
cp target/release/kimo-mcp crates/kimo-gui/binaries/kimo-mcp-$(rustc -vV | sed -n 's/host: //p')
cd crates/kimo-gui
echo '{"bundle":{"externalBin":["binaries/kimo-mcp"],"resources":{"../../fonts/":"fonts/"}}}' > tauri.release.json
npx --yes @tauri-apps/cli@2.12.3 build --bundles nsis --config tauri.release.json # Windows
npx --yes @tauri-apps/cli@2.12.3 build --bundles deb,appimage --config tauri.release.json # LinuxThe installers land in crates/kimo-gui/target/release/bundle/.
5. Connect a client
Client config. Use the absolute path of the binary you just built, for example /home/you/kimo/target/release/kimo-mcp.
Claude Code:
claude mcp add --transport stdio kimo -- /home/you/kimo/target/release/kimo-mcpClaude Desktop: add this to
claude_desktop_config.json(Settings, Developer, Edit Config) and restart the app. Theenvblock is optional;KIMO_TOOLS=corereturns a shorttools/list.
{
"mcpServers": {
"kimo": {
"command": "/home/you/kimo/target/release/kimo-mcp",
"args": [],
"env": { "KIMO_TOOLS": "core" }
}
}
}Cursor: put the same block in
~/.cursor/mcp.json(all projects) or.cursor/mcp.json(one project), then switch the server on in Cursor's MCP settings.Generic MCP client (stdio): command = the absolute path, no arguments, optional env as above. Any client that registers a stdio server by command and uses the
mcpServersshape takes the block as is.
The server itself (launch, initialize, tools/list) is verified on this build; the client config file locations come from each client's docs, not from a run of those apps here.
Codex and OpenCode use the formats shown under "Setup" below with the same path. KIMO_TOOLS=core (env var on the server entry) shrinks tools/list; see "Tool list profiles" below.
6. Quickstart with the CLI
State lives in a project file (--project p.kimo, created on first use). Every command below ran against this build; replace the media path with your own file.
K=target/release/kimo
$K -q call add_track --project p.kimo # prints {"track_id":"track1"}
$K -q call import_media --project p.kimo --args '{"path":"/abs/path/in.mp4"}' # returns asset_id, e.g. asset2
$K -q call add_clip --project p.kimo --args '{"track_id":"track1","source_type":"media","asset_id":"asset2","start":0,"duration":3}'
$K -q call add_title --project p.kimo --args '{"track_id":"track1","style":"lower_third","text":"Hello kimo","start":0.5,"duration":2}'
$K -q call render_frame --project p.kimo --args '{"time":1,"path":"/tmp/f.png"}' # look at one frame
$K -q call describe_frame --project p.kimo --args '{"time":1}' # numbers instead of pixels: stats, histogram, clipping, visible clips
$K -q call contact_sheet --project p.kimo --args '{"path":"/tmp/sheet.png","times":[0,1,2]}'
$K export p.kimo out.mp4 # render the timeline
$K tools search "color grade" # find tools by words
$K tools describe add_clip # argument schema of one toolIds (track1, asset2) are what the previous call returned, so read them from the output. export checks free memory first and refuses with a clear message when the frame would not fit; set KIMO_MEM_MB to override its budget. Exit codes: 0 ok, 1 tool error, 2 usage, 3 preflight failed. kimo --help lists every subcommand.
✦ Connect your AI
kimo is a standard MCP stdio server. Your client launches kimo-mcp itself; you only give it the path.
claude mcp add --transport stdio kimo -- ~/.local/bin/kimo-mcpcodex mcp add kimo -- ~/.local/bin/kimo-mcp{ "mcpServers": { "kimo": { "command": "/home/you/.local/bin/kimo-mcp", "args": [] } } }{ "mcp": { "kimo": { "type": "local", "command": ["/home/you/.local/bin/kimo-mcp"], "enabled": true } } }Quick check: echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | kimo-mcp should print "serverInfo":{"name":"kimo"....
Config formats were checked against each client's public docs on 2026-10-11; client configs change, so if one fails, check the linked page.
Claude Code
(docs)
claude mcp add --transport stdio kimo -- /home/you/.local/bin/kimo-mcpAdd --scope user to make it available in every project, or --scope project to write it to a shared .mcp.json. Check with claude mcp list, or type /mcp inside Claude Code. The same thing as a .mcp.json file in your project:
{ "mcpServers": { "kimo": { "command": "/home/you/.local/bin/kimo-mcp", "args": [] } } }OpenAI Codex (CLI and IDE extension)
(docs)
codex mcp add kimo -- /home/you/.local/bin/kimo-mcpOr edit ~/.codex/config.toml (or .codex/config.toml in a trusted project):
[mcp_servers.kimo]
command = "/home/you/.local/bin/kimo-mcp"Cursor
(docs)
Create ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):
{ "mcpServers": { "kimo": { "command": "/home/you/.local/bin/kimo-mcp", "args": [] } } }Then open Cursor's MCP settings and switch the kimo server on.
OpenCode
(docs)
Put this in opencode.json in your project, or in ~/.config/opencode/opencode.json for all projects. Note that OpenCode takes command as a list and uses type: "local":
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"kimo": { "type": "local", "command": ["/home/you/.local/bin/kimo-mcp"], "enabled": true }
}
}Any other MCP client
kimo is a standard MCP stdio server (protocol 2024-11-05, initialize, tools/list, tools/call). Any client that can register a stdio server by command works: give it the absolute path to kimo-mcp and no arguments. Many clients use the mcpServers JSON shape shown for Cursor; some (for example Zed) use a different key, so check your client's MCP docs for the exact file and format. Only the four clients above were checked against their docs.
Windows: use the path to kimo-mcp.exe (the Windows engine installer kimo-6.0.0-windows-x86_64-setup.exe installs per user, no admin rights, into %LOCALAPPDATA%\Programs\kimo by default, so the binary is %LOCALAPPDATA%\Programs\kimo\bin\kimo-mcp.exe (kimo.iss); in JSON write backslashes doubled, see the Windows guide). The configs above are the same except for the path; the Claude Code, Codex, Cursor and OpenCode formats were checked on their docs, not tested on Windows here.
3. Try it. Ask your assistant: "Use kimo to import /path/to/clip.mp4, add a title, and render a frame." Or drive it yourself with the Python client in examples/mcp_client.py.
KIMO_TOOLS picks what tools/list returns. Every tool can still be called by its own name under every profile.
Profile |
| Size | Use when |
| 17 | 4,432 bytes | small context windows. Call a group with |
| 29 | 20,368 bytes | the most used tools with full schemas, plus |
| 447 | 391,436 bytes | clients with large context or their own tool search. Every tool listed with its schema. |
| 30 | 20,537 bytes | small models cutting phone footage into a short: the recipe tools ( |
group names, e.g. | varies | varies | those groups listed flat, the rest grouped. |
Measured on a default-feature kimo-mcp built from commit af615ca (initialize, then tools/list; size is the compact JSON of the result); the flat row was re-measured the same way after flash_series, audio_spectrum, compare_ranges, contrast_ratio, text_contrast_series, edit_check, saliency_map, av_offset, frozen_frames, black_frames and focus_series were added, diff_frames gained quality, get_scopes its numeric arguments (and a first sentence naming them) query_safe_margins its rects, flash_series its flash rule numbers, 77 tools a short first sentence in front of their old description validate_captions its legibility numbers and lint_frame its quality numbers and decode_media and render_flow its stats numbers (v6, unreleased; grouped and core did not change). Re-measured again on commit 8644178 after the revision-safe transcript editing and preview proxy workflows (transcript_edit, transcript_search, proxy_tools) landed: flat is 447 entries, 391,436 bytes (grouped, core and director entry counts unchanged; their byte counts were not re-verified this pass). kimo_enable_group is listed in grouped and core but not in flat. search_tools(query, limit=8, group?) returns ranked tools, effects and transitions with the required args and a call_as hint.
Set it like this: claude mcp add --transport stdio --env KIMO_TOOLS=core kimo -- /home/you/.local/bin/kimo-mcp, or [mcp_servers.kimo.env] KIMO_TOOLS = "core" for Codex. For JSON configs add "env": { "KIMO_TOOLS": "core" } (OpenCode: "environment": { ... }).
✦ What it can do
452 tools in 14 groups. 438 are live in the default build; 16 more are feature-gated (OCIO, mesh import) and answer with a clear refusal until built in.
Area | Groups | Examples |
Editing |
| tracks, clips, trims, ripple and roll edits, speed ramps, cut on the beat (beat_cut), scene auto-split (scene_split), multicam, markers, paste attributes, atomic |
Motion |
| keyframes and Bezier easing, audio to keyframes, jump-cut punch-ins, expressions, camera and shake, corner pin, transitions, morph cut (optical-flow jump-cut smoothing), push and gradient wipes, blur fill for vertical video, lens blur (iris bokeh defocus), depth parallax (3D photo camera move from a depth map), displacement map, adjustment layers |
Compositing |
| mask layers and roto, shapes and path operators (wiggle, zig zag, pucker/bloat, twist, round corners), HUD frames, counters, boxes |
Text |
| titles, captions, SRT import, text animators |
VFX |
| code clips (a web page / three.js project drawn per frame), particles, emitters, shard bursts, 3D scene, physics, lights and materials, 3D layer compositor (depth sort, plane intersections, cast shadows, depth of field) |
Tracking |
| auto reframe (subject-following crop to the canvas aspect), point, planar and mesh tracking, warp stabilize (smooth or locked, position / similarity / perspective, crop + auto-scale or synthesized edges, rolling-shutter repair), camera solve |
Color |
| grade graphs, curves, ASC CDL, LUTs, ACES and OCIO tools, scopes, exposure analysis, flash series and WCAG contrast (also of text over moving video) |
Audio |
| clips, effects, beats, loudness, ducking, speech intervals, spectrum and band energy, A/V offset (audio onsets vs picture change, lag in ms) |
Output |
| frame and video export, chunked export jobs, GIF, EXR, manifests, frame lint, contact sheets, PSNR / SSIM / MS-SSIM comparisons, edit checks (changed regions inside / outside allowed rects), saliency maps (where the eye goes, mass inside given rects), frozen-frame runs over a range (start, end, length, largest pixel difference), near-black runs over a range (whole frame near-black, start, end, length, brightest pixel), sharpness per frame (Laplacian variance and Sobel gradient of luma, whole frame and rects) |
Get any tool's arguments with kimo tools describe <name> or kimo_describe, and find tools by words with search_tools. A group can be called as {"name": "vfx3d", "action": "add_scene3d", "args": {...}}, or call any tool by its own name.
Group | Tools |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Drive it from the CLI too
K=target/release/kimo
$K -q call add_track --project p.kimo # {"track_id":"track1"}
$K -q call import_media --project p.kimo --args '{"path":"/abs/path/in.mp4"}' # -> asset2
$K -q call add_clip --project p.kimo --args '{"track_id":"track1","source_type":"media","asset_id":"asset2","start":0,"duration":3}'
$K -q call add_title --project p.kimo --args '{"track_id":"track1","style":"lower_third","text":"Hello kimo","start":0.5,"duration":2}'
$K -q call render_frame --project p.kimo --args '{"time":1,"path":"/tmp/f.png"}'
$K export p.kimo out.mp4
$K tools search "color grade"✦ Made with kimo
Frames from short films rendered end to end by kimo. Each one started as a prompt, and an agent built every frame through MCP tool calls.
✦ How it works
flowchart LR
agent["AI agent<br/>(Claude Code, Codex, Cursor, OpenCode, any MCP client)"]
subgraph engine["kimo-mcp: the headless engine"]
direction TB
reg["command registry<br/>tools/list is generated from it"]
core["kimo-core<br/>project model, CPU renderer,<br/>color, audio, text, tracking, 3D"]
prev["preview thread<br/>one auto frame after mutating calls"]
reg --> core --> prev
end
ff[("ffmpeg / ffprobe")]
gui["kimo app (kimo-gui)<br/>editor + agents, owns the engine"]
agent -- "JSON-RPC over stdio<br/>tools/call is the only way to edit" --> reg
core <-- "decode / encode / probe" --> ff
engine -. "telemetry JSONL on 127.0.0.1:7421<br/>call events, frame_rendered, frame_skipped" .-> guiHeadless engine.
crates/kimo-coreholds the project model, keyframes, the command registry, tool groups, the CPU renderer, effects, text, audio, tracking and color.crates/kimo-mcpis the MCP stdio server;kimo(crates/kimo-cli) is a command line client for the same tools. Decode, encode and probing go throughffmpegandffprobe. The renderer is CPU only; GPU code is off by default.Edits only through MCP tool calls. Add a tool to the registry and it appears in the MCP server, the CLI, the fuzz test and the schema. There is no side door.
The app owns the engine, and every agent shares it.
crates/kimo-gui(a Tauri app, its own Cargo workspace) launches kimo-mcp as a sidecar and opens a loopback bridge.kimo-gui mcp, which Claude Code, Codex and Antigravity launch, attaches to that bridge while the app is open, so you, the agents you run from the Agent tab and the agents in your own terminal all edit one project with one undo history. Every call is tagged with who made it (Live tab) and every change gets an Undo card. With the app closed,kimo-gui mcpruns a standalone engine exactly likekimo-mcp.
More: docs/ARCHITECTURE.md, docs/EXTENDING.md, crates/kimo-gui/README.md. An agent editing phone footage into a 9:16 short, call by call: docs/DIRECTOR_QUICKSTART.md.
Kimo's spectator app (crates/kimo-gui) connects on its own. Open it and every tool call streams to it live; you don't
set anything. With KIMO_SPECTATOR unset or empty (or on), kimo-mcp looks for the app on loopback ports
127.0.0.1:7421–7430, in order. It never uses 0.0.0.0 or any other host. It only streams to a peer that answers the
versioned spectator handshake (KIMO-SPECTATOR/1; any other answer, an older version included, is a failed
handshake), so a different program holding one of those ports gets nothing. The search runs on the telemetry thread,
never on a tool call. The app takes the first free port in that range and shows "listening 127.0.0.1:".
KIMO_SPECTATOR=off (or 0/false) turns telemetry off: no telemetry thread, no events.
KIMO_SPECTATOR=tcp://127.0.0.1:<port> pins one port with no scan and no handshake; a host that is not a loopback
address (127.0.0.1, localhost) is ignored and telemetry stays off. file:/path/events.jsonl writes the same lines to
a file. A malformed value is treated as off, silently. With no app connected, events are dropped before they are
serialized, and nothing about telemetry is written to stdout or stderr. With an app connected, each tool call sends
a start event with the arguments, progress for long calls such as export, and complete with what changed in
the project (or error), all under one call_id. The stream is
out of band: tools/list, results and stdout are byte-identical with it on or off, it never waits for the app,
and with no app listening events are dropped. The app can be opened and closed at any point in a session: the
engine notices a closed window before its next event, reconnects on its own (retrying after 50 ms, doubling to
at most 1 s between attempts, never waiting on the tool calls), and events from while no app was listening are
dropped rather than replayed.
The viewer follows the project live: after any call that changes it (import, add/move/trim/split a clip,
transforms, effects, colour, text...), the engine renders the frame at the playhead in the background and sends it as
{"type":"frame_rendered","auto":true,"png_b64",...} (at most 640 px wide; KIMO_SPECTATOR_FRAME_PX changes that),
so the app never waits for the agent to call render_frame. Read-only calls (get_*, list_*, searches,
tools/list) render nothing. Bursts coalesce, latest wins: the frame renders once no call has arrived for 40 ms (or
400 ms into a long burst, between two calls), one at a time, never while a call is running, on its own thread with
its own decode cache, so tool calls never wait for it. The playhead moves to an explicit time/at (a split shows
the cut), else into the clip the call touched, and otherwise stays put. Frames are only rendered while an app is
connected (one that opens mid-session gets the current frame at once); with telemetry off or nobody listening
there is no render thread at all (with nobody listening, events are dropped before they are serialized and the
telemetry thread looks for the app again at most once a second), and KIMO_SPECTATOR_FRAMES=0 keeps the call events but turns the frames off.
The {"type":"session"} event and every {"type":"project_changed"} carry the project width and height in pixels
(the size after the call), so the app can place x/y transform moves on the viewer.
export progress events carry current_frame (frames finished, so the index of the next frame), total_frames,
fps (the instantaneous rate over the time since the previous progress report) and eta_ms (null until the first
frame is done) beside pct and elapsed_ms. To watch in a plain browser instead of the app, run
python3 crates/kimo-mcp/tools/spectator_sse_relay.py and open the UI with ?feed=sse. Event fields:
crates/kimo-mcp/src/spectator.rs.
Call events are strictly one per call: every tools/call gets exactly one start and exactly one complete or
error, in call order, with its call_id and the request's JSON-RPC id as rpc_id, and one project_changed per
call that changed the project. They travel on their own lossless lane: never coalesced, never dropped while an app is
connected, and written as whole lines only. An app that is slow to read (a busy window) is waited for, not cut off.
Memory is bounded at 64 MiB of queued events; past that, the next call waits for the app to catch up (backpressure)
rather than losing anything, and nothing ever waits while no app is listening. Canvas frames have a separate
latest-only lane (the newest two), so they can never crowd out, drop or delay call events. Only the headless canvas
frames below coalesce.
Every headless frame a call queues ends as exactly one frame_rendered (auto) or one
{"type":"frame_skipped","skip_reason",...,"call_id","rev","gen","frame_lane_drops","ts_ms"}. Refusals
(memory_budget, session_busy, pq_output, hlg_output, render_error, render_panic) also carry
"refused": true and a human reason, and the spectator shows them as a "render refused" chip. Benign skips
(coalesced, superseded_by_render_frame, frame_lane_dropped, disconnected) mean a newer frame replaces this one
and carry no reason. Details: crates/kimo-mcp/src/preview.rs ("Headless skips").
Two preview modes
Headless (default). As described above: canvas frames coalesce by call cadence, so a burst of 59 calls 50 ms apart shows about 6 frames, and the tool calls never wait for the viewer. Use this for agents and batch runs.
Spectator demo mode (opt in). For watching or recording a session: every tool call gets its own canvas frame, rendered from the project exactly as that call left it and tagged with it (
"demo":true,seq,call_id,rpc_id,tool). After each call's response the engine holds the next request until that frame has reached the app and a pace (50 to 100 ms, default 75) has passed, so each call's change stays on screen. A call that leaves the picture unchanged (a read, a failed call) re-sends the current frame with"same":true. Demo frames travel on the lossless call-event lane, never the latest-only one, so none is dropped. A frame that cannot be made is sent as{"type":"frame_skipped","demo":true,"reason":...}, so frames and calls always match one to one. Turn it on withKIMO_SPECTATOR_DEMO=on(or a pace in ms, e.g.KIMO_SPECTATOR_DEMO=60), or on the command line withkimo-mcp --spectator-demoorkimo-mcp --demo-pace-ms 60(the command line wins). It needs telemetry on (the default; not withKIMO_SPECTATOR=off), and it does nothing (no pacing, no renderer) while no app is connected. Example:claude mcp add --transport stdio --env KIMO_SPECTATOR_DEMO=75 kimo -- /home/you/.local/bin/kimo-mcp. Pacing was chosen over rendering every frame without waiting because unwaited frames would be rendered after the agent had already moved on, so the canvas would trail the timeline and inspector and show the wrong state for a call.
✦ Docs
How the engine, registry and spectator fit together | |
Add a tool to the registry | |
An agent cutting phone footage into a 9:16 short, call by call | |
Edit video by editing words | |
Lighter editing media, original-quality exports | |
Signed in-app updates, opt-in crash reports, crash recovery with Undo | |
🧪 Testing | The test suites and what CI runs |
What's solid, beta and not built | |
Where it's going and what changed |
Registry: 452 tools (
crates/kimo-core/tests/golden/golden_registry.txt, 452 lines). A default-featurekimo-mcplists 454 entries inflatmode: those 452 plussearch_toolsandkimo_describe. Of the 454, 438/454 live in the default build + 16 feature-gated (8 native-ocio, 8 mesh-import/material-textures/flat-sah).flash_serieson the jaja ad (v6, unreleased): the 30.542 s luminance stamp is a slow fall (0.894 to 0.794 as the logo fades in), not a hard cut. Under rule (a) a transition is stamped at the first frame whose luminance has moved 0.1 from the swing start, so this stamp is expected behaviour, not a bug.Fuzz: 6497 calls, 0 failures, as recorded in the v3 notes at 327 tools. Not re-run for this README.
Linux spectator installers (
.deb,.AppImage): built on CI runners (dry run atca0334f, then version0.1.0; the5.0.0files come from the same steps in thev5.0.0tag build), downloaded and smoke-tested on Debian 12 x86_64 on 2026-10-17: sha256 matches, the.debinstalls (Depends: libwebkit2gtk-4.1-0, libgtk-3-0) and uninstalls cleanly, and both the.deband the AppImage (--appimage-extract-and-run) launch under Xvfb, listen on 127.0.0.1:7421 and draw theframe_renderedframes a realkimo-mcp(commitaf615ca) sends afterproject_set,add_track,add_text. Unsigned draft; other distributions not tested.Windows spectator installer (
Kimo-Spectator_5.0.0_x64_en-US.msi): unsigned draft, built on CI runners. CI installs, launches and uninstalls it on a GitHub Windows runner (thev5.0.0tag build); not installed on a real Windows PC yet.Engine release jobs: the Linux engine tarball is glibc only for this release (the static musl build was dropped). The Windows x64 engine job failed in the first dry run in
crates/kimo-core/build.rs(MSBuild rejectscmake --build ... -- -j1). This release switches tocmake --build ... --parallel 1and links the C++ runtime per target (libstdc++on Linux,libc++on macOS, nothing on MSVC); the Windows engine job then passed on CI (thev5.0.0tag build) and its zip and setup.exe are attached. Not run on a real Windows PC yet; macOS not built.Windows engine build from clone: not run here.
Third-party licences for the spectator app: THIRD_PARTY.md (five MPL-2.0 crates from the Tauri stack and the LGPL libraries bundled in the AppImage, both decision pending).
Per-feature limits and change notes: docs/DEV_NOTES.md. Feature tiers: FEATURES.md. Plans: ROADMAP.md.
Coherent fields (feature-branch WIP)
This feature branch adds original raw 2D Perlin/simplex fields, analytic gradients, MCP point sampling and an animatable noise effect. It is not part of the finalized v3 release. Compilation, numeric tests, warning delta and real 1080p visual sign-off are pending. No quality or production-readiness claim is made. See the noise plan and verification commands. The next WIP field units add explicit Euclidean Worley F1/F2, FBM, domain warp and 2D potential curl. These are independently selected raw operators, not presets. They are also uncompiled and unrendered here. See field units.
Camera math primitives (feature-branch WIP)
Explicit-pose projection and camera-space near-plane clipping are drafted as raw MCP math tools. Uncompiled, unrendered, not integrated into the legacy renderer. They do not yet fix existing Scene3D output. See camera WIP.
Raw UV math (feature-branch WIP)
Uncompiled original push/radial coordinate primitives, MCP-callable but not a rendered transition. See UV WIP. No visual sign-off.
Particle simulation primitive (feature-branch WIP)
Uncompiled raw fixed-step 3D trajectory + force/swept-plane math. No emitter or renderer adapter yet, no visual sign-off. See particle WIP.
✦ Contributing
Issues and PRs welcome. One rule: the README ships with the product. If a change adds, removes or regroups tools, or ships a new proof, the same commit updates this file.
MIT licensed · LICENSE · Third-party notices
Built in Rust. Driven by your AI. getkimo.tech
Available Tools
17 toolsanimateD
Properties, keyframes and curves, expressions, motion paths and presets, camera, blend, corner/mesh... [32 actions]
Inputs: action (required), args.
audioC
Audio levels, effects, pan, ducking, loudness normalize, beat detection, audio export. [17 actions]
Inputs: action (required), args.
color_gradeC
Grading: primaries, curves, wheels, node graphs, LUTs, CDL, match grade, white balance, shared... [22 actions]
Inputs: action (required), args.
color_scienceD
Color pipeline: ACES, OCIO, HDR, float and high bit depth, color management, delivery checks and... [18 actions]
Inputs: action (required), args.
effectsC
Video effects, transitions, adjustment layers, effect masks and effect presets. [15 actions]
Inputs: action (required), args.
graphicsD
Shapes, bezier paths, shape modifiers, layer styles, HUD frames, counters, detection boxes. [20 actions]
Inputs: action (required), args.
kimo_describeC
Full description and argument schema of one action (action) or the action list of a group (group).
Inputs: group, action.
kimo_enable_groupC
List every tool of a group individually from now on (the server sends notifications/tools/list_changed).
Inputs: name (required).
masksD
Masks, roto, track mattes, matte refinement and keying. [16 actions]
Inputs: action (required), args.
outputC
Render a frame or export video, GIF, alpha, presets, EXR/TIFF, LUTs, camera solves. [40 actions]
Inputs: action (required), args.
projectC
Project settings, media import, save/load, undo/redo, inspect the project. [35 actions]
Inputs: action (required), args.
scopesC
Scopes and measurement: waveform/vectorscope, exposure analysis, false color, gamut checks... [12 actions]
Inputs: action (required), args.
search_toolsB
Find a tool, effect or transition by keywords. Returns ranked matches with required args and how to call each. Call any listed name directly.
Inputs: query (required), group, limit.
textD
Text, titles, text animators and paths, captions, subtitles, fonts, transcription. [23 actions]
Inputs: action (required), args.
timelineC
Tracks and clips: add, move, trim, split, ripple/roll/slip/slide, speed, markers, multicam, silence... [37 actions]
Inputs: action (required), args.
trackingC
Point/planar/mesh/feature tracking, stabilize, camera solve, lens undistort, track validation and... [25 actions]
Inputs: action (required), args.
vfx3dD
3D scenes, lights and materials, relight, particles, shard bursts and fracture glass. [15 actions]
Inputs: action (required), args.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool maps to a broad domain, so an agent can generally choose correctly. Some boundaries blur between color_grade, color_science, and scopes, and between effects, masks, and tracking, but the descriptions provide enough signal.
Most tools use lower_snake domain names with no verbs, which is predictable. Minor deviations are vfx3d lacking a separator and helper tools using a kimo_ prefix while core group tools do not.
17 group tools is slightly above the typical 3-15 range, but each groups a large feature area with dozens of actions, so the surface is not redundant. It is reasonable for a full editing/compositing suite, though a few groups could possibly be merged.
Coverage spans project management, timeline editing, animation, effects, masks, audio, text, graphics, 3D/VFX, tracking, grading, color science, scopes, and output, plus search/describe/enable helpers. No obvious lifecycle gap exists for a video editing suite.
Maintenance
Related MCP Connectors
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
MCP server for the FFmpeg Micro video transcoding API — create, monitor, download transcodes.
Hosted MCP tools for FFmpeg-style video and audio processing through FFMPEG API.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA basic MCP server implementation for testing purposes. Communicates via stdio and is designed to work with MCP-compliant clients.-
- FlicenseAqualityDmaintenanceMCP server for taking Linux / Wayland screenshots via grim and slurp.2-
- AlicenseAqualityDmaintenanceEnables LLMs to perform FFmpeg operations like clipping, merging, extracting audio, adding subtitles, and transcoding videos via a set of tools exposed as an MCP server.58MIT
- FlicenseAqualityCmaintenanceMCP server that wraps MiniMax platform APIs (speech, video, image, music, and file management) as tools over stdio, enabling natural language interaction with MiniMax's AI services.161-