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

01

Described timeline — cuts, motion, steps, flicker, flashes and gradual change, each with a timestamp, a region and a plain-English description

02

Finds the thing with no pixels — a stall, where continuous animation stopped and resumed, is invisible to anything that only looks for change

03

Sub-threshold detection — gradual fades too slow to clear the frame-to-frame threshold are still reported

04

Activity maps — a PNG where every pixel keeps its source x,y: red is how much it changed, green when, blue how often

05

Contact sheets — one labelled PNG of many real frames, so you can see the whole recording in a single image

06

Pixel-exact compare — how two moments differ, with the difference drawn

07

Honest about fit — a suitability verdict flags panning cameras, scrolling pages and ambient motion instead of returning confident nonsense

08

check exits non-zero — assert conditions so a visual regression breaks a build

09

MCP server built in — the same commands over MCP for clients that do not speak shell

10

next_steps and limits on every result — runnable follow-up commands, and what the run could not have seen

11

One runtime dependency — ffmpeg and ffprobe on PATH, or pointed at explicitly with --ffmpeg / --ffprobe; no credentials, no network, no service

12

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

>_ The described timeline
$ agent-motion timeline recording.mp4
>_ See the whole recording as one labelled sheet
$ agent-motion sheet recording.mp4
>_ Where change happened, not just when
$ agent-motion activity recording.mp4
>_ Filter the timeline for layout shifts
$ agent-motion timeline recording.mp4 --format jsonl | grep '"kind":"shift"'
>_ Exactly how two moments differ
$ agent-motion compare recording.mp4 --at 14.9,18.5
>_ Timeline plus an activity-map PNG
$ agent-motion project recording.mp4
>_ Break the build on a visual regression
$ agent-motion check recording.mp4