A 100-frame ceiling makes this a sampled review
claude-watch gives an agent evidence it can already consume: JPEG frames and text. A URL goes through yt-dlp, while a local file is read in place. ffmpeg extracts one frame around each detected scene change, native captions provide the first transcript option, and Whisper handles videos without captions. The resulting report includes a summary, moments, hook notes, entities, concepts, and source material for the agent to fill. That is enough for many editorial questions without pretending the model played the file continuously.
The hard limit is 100 frames at no more than 2 fps. Clips under 30 seconds target about 30 frames, while videos longer than 10 minutes receive the full 100-frame budget spread sparsely. A focused --start and --end range spends the same budget on a smaller window. This design controls image-token use, but it also means a quiet on-screen change between samples can be missed. Use the output as a guided skim, not a frame-accurate account.
The first 10 seconds get a separate dense pass
The hook microscope samples the opening 10 seconds at 2 fps and requests word-level Whisper timing. That lets an agent compare what appeared on screen with what the speaker said at the same moment. Scene pacing is also estimated from shot count and shot length. For a creator studying intros, those artifacts are more useful than a transcript alone because a title card, product reveal, or cut can carry meaning that nobody says aloud.
Scene detection is still a heuristic. A static screencast may contain meaningful cursor, text, or state changes without a large visual cut. Open pull request 9 describes a 17-minute, 43-second screencast where 13 detected frames left gaps of more than 4 and 6 minutes. That report is not proof that every source build behaves the same way. It is a concrete reason to check timestamp coverage and rerun a focused range when the initial report looks thin.
What happened when we ran it
Our sandbox cloned commit 7711231 and installed 35 packages in 12 seconds. The installed environment occupied 37 MB, compared with the 0.1 MB checkout. Building succeeded in 4 seconds. The repository contained 28 files and about 2,361 lines of source, with 1 CI workflow, no Dockerfile, and no top-level tests directory. Pip-audit found 0 known vulnerabilities in the Python environment.
The harness found no test script or target, so it skipped tests rather than recording a pass. That distinction matters for a pipeline that shells out to downloaders, media tools, and hosted transcription APIs. We did not download a video, extract frames, call Whisper, open Obsidian, or compare a generated report with its source. The 12-second install and 4-second build prove packaging mechanics at commit 7711231, not video-analysis accuracy.
ffmpeg 9 can stop scene extraction before analysis
Open issue 13 reports that ffmpeg 9.0.1 rejects the -vsync option used by the scene-change command. The issue includes a direct reproduction and says -fps_mode works on that version. Two open pull requests propose related compatibility fixes, including one that probes support and retains a fallback for older ffmpeg releases. Until a fix lands, a fresh media-tool install can be less reliable than the README's first-run flow suggests.
Windows has a separate output problem. Issue 14 reports a UnicodeEncodeError when Python 3.13.15 prints an arrow through a cp1252 console during a focused run. The reporter says setting PYTHONIOENCODING=utf-8 avoids the crash. An open pull request addresses broader non-Latin output, but it was not merged when fetched. Windows users should test one short local clip before relying on batch work or multilingual transcripts.
Caption-less audio may leave the machine
Native captions are the cheapest path because yt-dlp obtains them directly from the video host. If none exist, claude-watch extracts mono 16 kHz audio and sends it to Groq's whisper-large-v3 or OpenAI's whisper-1, depending on the configured key. The README says it does not upload the video itself. For confidential meetings or customer recordings, sending the audio is still an external disclosure that needs an explicit policy decision.
The Whisper path has a 25 MB upload ceiling, described as roughly 50 minutes at the chosen audio settings. Focused ranges can keep an upload below that boundary. --no-whisper prevents external transcription and leaves a caption-less source with frames only. The current documented release does not offer a local speech model, although a closed pull request proposed one. Teams with a strict local-processing requirement should pair yt-dlp and ffmpeg with a separately managed local Whisper installation instead.
Three installation surfaces do not behave identically
Claude Code installs the project as a marketplace plugin, Claude web takes a packaged skill file, and Codex uses a cloned skill directory. The shared Python scripts do the media work, but hooks, command exposure, file permissions, and image-reading behavior depend on the host agent. Obsidian integration is optional: WATCH_VAULT_DIR selects a vault, after which the workflow can stage the report and chosen frames and ask whether to ingest them.
GitHub listed 705 stars, 10 combined issues and pull requests, and a last source push on July 24, 2026. The latest release was v0.2.0 from May 25, while new compatibility reports and pull requests arrived through August 28. A stale tag alone does not settle project health, but the gap means the packaged web skill may not contain proposed fixes visible in open branches. Pin the commit you test and keep ffmpeg behavior in the acceptance check.