agent-motion
Find out what happens in a video over time, without watching it
- Language
- Go
- Version
- 0.1.1
- License
- PolyForm Perimeter 1.0.0
- Category
- CLI Tool
A temporal video analysis CLI for AI agents. It decodes a recording locally and returns a described timeline — what changed, when, where on screen, and what shape the change had. Cuts, movements, flickers, flashes, gradual fades and stalls come back as text at a fraction of the cost of the frames they summarise, and every result says what that run could not have seen.
Features
Described timeline — cuts, motion, steps, flicker, flashes and gradual change, each with a timestamp, a region and a plain-English description
Finds the thing with no pixels — a stall, where continuous animation stopped and resumed, is invisible to anything that only looks for change
Sub-threshold detection — gradual fades too slow to clear the frame-to-frame threshold are still reported
Activity maps — a PNG where every pixel keeps its source x,y: red is how much it changed, green when, blue how often
Contact sheets — one labelled PNG of many real frames, so you can see the whole recording in a single image
Pixel-exact compare — how two moments differ, with the difference drawn
Honest about fit — a suitability verdict flags panning cameras, scrolling pages and ambient motion instead of returning confident nonsense
check exits non-zero — assert conditions so a visual regression breaks a build
MCP server built in — the same commands over MCP for clients that do not speak shell
next_steps and limits on every result — runnable follow-up commands, and what the run could not have seen
One runtime dependency — ffmpeg and ffprobe on PATH, or pointed at explicitly with --ffmpeg / --ffprobe; no credentials, no network, no service
Every entry point guards on the executable it runs — a missing or wrong ffmpeg fails with a clear message up front, not partway through a decode
Install
Homebrew
$ brew install shhac/tap/agent-motion Required dependency — ffmpeg (supplies both ffmpeg and ffprobe)
$ brew install ffmpeg AI Agent Skill
$ npx skills add shhac/agent-skills --skill agent-motion --global GitHub Release (macOS)
$ curl -L https://github.com/shhac/agent-motion/releases/latest/download/agent-motion-darwin-arm64.tar.gz | tar xz Go Install
$ go install github.com/shhac/agent-motion/cmd/agent-motion@latest Build from Source (needs Go 1.26+)
$ git clone https://github.com/shhac/agent-motion.git && cd agent-motion && make build Getting Started
agent-motion needs no credentials and reaches no network — it decodes locally. Its one runtime dependency is ffmpeg, which supplies both the ffmpeg and ffprobe binaries. Building from source additionally needs Go 1.26+.
01 · Install the one dependency
$ brew install ffmpeg agent-motion shells out to ffmpeg and ffprobe and expects both on PATH. If they live somewhere else, point at them with --ffmpeg and --ffprobe rather than changing PATH.
02 · Check the file without decoding it
$ agent-motion inspect recording.mp4 Dimensions, frame rate, duration and codec. Costs nothing — no decoding pass.
03 · Read the timeline
$ agent-motion timeline recording.mp4 One decode pass returns the described timeline plus a suitability verdict. This is the right first call.
04 · Narrow to the moment that matters
$ agent-motion timeline recording.mp4 --start 17 --end 19 --threshold 4 Re-run bounded and more sensitive once the timeline points at a window.
05 · Look at it
$ agent-motion frames recording.mp4 --at 17.62 --region 200,120,202,160 --pad 24 --width 480 Real source frames at chosen timestamps, cropped to a region and magnified for something too small to see full-frame.
Usage
$ agent-motion timeline recording.mp4 $ agent-motion sheet recording.mp4 $ agent-motion activity recording.mp4 $ agent-motion timeline recording.mp4 --format jsonl | grep '"kind":"shift"' $ agent-motion compare recording.mp4 --at 14.9,18.5 $ agent-motion project recording.mp4 $ agent-motion check recording.mp4