2.1.0
Added
- The tool has its own icon, in a dark and a light version. Codex shows it on the plugin card and in the skill list, and the toolkit site shows it on the tool's page and in share previews.
watch-video
Watch / analyze a video or audio source the agent cannot natively play. A URL from YouTube, TikTok, Instagram, X, Facebook, Vimeo, Reddit, Twitch, LinkedIn or 1750+ other sites, or a local file. Downloads it, pulls captions (or transcribes locally when there are none), and extracts frames so the agent can Read the transcript + frames and describe pacing, hooks, on-screen text, format, or answer questions about the content. No API key needed.
Say this you do not type commands, you ask
- “watch this video”
- “analyze this short/reel/clip”
- “what happens in this video”
- “reverse-engineer this video”
- “read the frames of”
- “transcribe this video”
- “/watch-video”
Once it is installed, that is the whole interface. Your agent picks the skill up on its own and runs whatever it needs to. The commands further down are there for anyone who would rather drive it themselves.
Install pick your agent
Requirements what to install, and why
bash scripts/setup.sh --check # what's installed, what's missing
bash scripts/setup.sh # shows a plan, asks, installs
bash scripts/setup.sh --yes # non-interactive
bash scripts/setup.sh --with-whisper # add free offline speech-to-text
Detects your platform and package manager — Homebrew, apt, dnf, pacman, zypper, apk, pipx/pip — and prints every command before it runs. Nothing is installed without a confirmation or an explicit --yes, and anything needing root is shown in full first.
| Tool | Needed for | Notes |
|---|---|---|
ffmpeg |
always | Frames and media metadata |
yt-dlp |
URLs only | Installed via pip where distro packages go stale |
| a whisper engine | optional | Free and local. Used automatically when a source has no captions. setup.sh picks mlx-whisper on Apple Silicon, whisper-ctranslate2 elsewhere |
Options every flag
| Option | Default | Meaning |
|---|---|---|
--frames N |
30 (max 60) | Target frame count |
--width W |
480 | Frame width in px |
--start SEC / --end SEC |
— | Sample a time range only |
--lang CODE |
en.* |
Caption language, e.g. ar.*, all |
--scenes |
off | One frame per visual cut |
--no-whisper |
off | Skip local transcription even if an engine is installed |
--whisper-model M |
base |
Speed vs accuracy, e.g. large-v3 |
--yes |
off | Accept prompts, including installing a transcriber |
--cookies BROWSER |
— | Login-gated videos, e.g. chrome |
--playlist N |
single | Allow a playlist, take first N |
--outdir DIR |
temp | Where output lands |
--keep-video |
off | Keep the download |
Examples copy and go
How it works step by step
yt-dlpfetches the media (capped at 1920px tall) plus auto or uploaded subtitles, converted to.srt. Local files skip this step. Playlists are refused unless--playlist Nis given, so one URL means one video.ffprobereads duration and dimensions. A source with no video stream is handled as audio-only: transcript, no frames.- If the requested language has no captions, it retries for captions in any language. If there are still none, an installed whisper engine transcribes locally — free and offline, no API key.
ffmpegextracts frames, either at an even interval or on scene changes with--scenes. Scene mode falls back to even sampling when a source has too few cuts to be useful.- A manifest prints the transcript path, frame paths and source metadata for the agent to read.
Limits what it will not do
- Reads publicly accessible media. It does not bypass paywalls or DRM.
--cookiesreuses a session you are already signed into; it does not defeat access control. - Long videos download in full before framing. Prefer
--start/--end. - Local transcription is accurate but much slower than downloading a caption file, so captions are always tried first.
--no-whisperskips it entirely. - If a source that used to work stops downloading, yt-dlp is usually out of date —
setup.shupdates it.
Changelog what changed, newest first
2.0.0breaking
Breaking
- Installed as a Claude Code plugin, the slash command is now
/watch-video:watch-video, with the plugin name in front. This has been true since 1.3.0, and this release marks it as breaking. Use the new name, or ask in words, which works as before. A copy in a skills folder keeps the plain name/watch-video.
Added
- Codex now shows a display name, a short line and a starter prompt for the skill in its skill list. They come from a generated
agents/openai.yamlinside the skill folder. Other agents ignore that file.
Changed
- The description now leads with what the skill does, then its trigger phrases, then the detail. Codex shortens long skill lists from the end, so the phrases that route a request now survive far longer. With 40 skills installed, 95% of the phrases stay visible instead of 8%.
1.3.0
Added
- Can be installed as a Codex plugin, from the same source as everything else.
Changed
- The changelog address now points to the site, so it keeps working if the repository layout changes.
1.2.0
Added
- This changelog, so you can see what changed in each version.
- An Updates section in
SKILL.md. It tells the agent how to check for a newer version, and to report what changed before it updates.
1.1.1
Changed
- The docs now say which platforms it runs on: macOS and Linux, and Windows through WSL or Git Bash.
1.1.0
Added
- A setup wizard that checks for ffmpeg and yt-dlp and installs them.
- Automatic transcription when a source has no captions.
- An optional free local engine for transcripts that runs offline.
Fixed
- Playlists and audio-only sources are handled.
1.0.0
Added
- Watch a video from a URL or a local file. It pulls captions and extracts frames the agent can read.
An agent that has this installed reads CHANGELOG.md in the skill folder.
The same history is at changelog.json,
and every tool's releases are at /updates.json.
Built at Itqan Lab, a design and technology studio.
إتقان — itqan, the Arabic word for mastery: doing a thing precisely, and completely.