Primary question: Does your agent harness support SKILL.md skills and Claude-compatible image Reads, and are you comfortable with yt-dlp and ffmpeg as local dependencies?
RepoDaily adoption score
RepoDaily rates this as 91/100 (strong) for adoption: evidence, installation path, production risk, differentiation, license clarity, and AI/agent fit are scored from the article sources and adoption notes.
4 source(s) across 4 source category/categories, plus a RepoDaily-specific evidence module when available.
5 workflow step(s), 5 next-action step(s), and 5 command/install signal(s) were detected.
Trending momentum is +948 stars, with maintenance/release/issue signals counted when present.
Risk is marked medium, with 5 security note(s) and 4 explicit skip condition(s).
3 opportunity lens item(s), 4 alternative(s), and 3 type-specific section(s) support differentiation.
License source or license wording is present.
6 AI/agent-related signal(s) were detected in the article text and metadata.
Project overview
claude-video is a Python skill that extends Claude and 50-plus Agent Skills hosts with a single slash command, /watch. You paste a URL or local file path, ask a question, and the skill fetches captions, downloads only what the run needs, extracts scene-aware frames, pulls a timestamped transcript, and feeds every frame as an image into the model. By the time Claude answers, it has visually inspected the video and read the audio track.
The repository positions itself against a real gap: agents can browse pages, run scripts, and read repos, but they cannot watch video. Pasting a YouTube link usually leaves the model guessing from a title or reading an incomplete transcript. claude-video closes that gap by orchestrating yt-dlp for source handling, ffmpeg for frame extraction, and either native captions or a Whisper backend for transcription.
Installation is designed to be low-friction. On Claude Code you add the marketplace and install the watch plugin. On Codex, Cursor, Copilot, Gemini CLI, or other Agent Skills hosts you run `npx skills add bradautomates/claude-video -g`. yt-dlp and ffmpeg install on first run via Homebrew on macOS, while Linux and Windows print the exact commands to run. Captions cover most public videos for free, and a Whisper API key is only required when a video has no captions.
The 0.2.0 release, dated 2026-06-29, restructured the project into a self-contained `skills/watch/` package so that SKILL.md and its scripts ship as siblings. That fixed a concrete defect: non-Claude installs via `npx skills add` had previously copied SKILL.md without the scripts it shells out to, leaving the skill dead on arrival on Cursor, Codex, and similar hosts.
Why it is trending now
- 948 period stars at trending rank 5, driven by demand for agents that can reason over video rather than guessing from titles.
- Fills an obvious capability hole: Claude, Codex, Cursor, Copilot, and Gemini CLI can browse text and code but cannot natively watch video.
- Broad host support through the Agent Skills ecosystem, plus a one-line Claude Code marketplace install.
- 0.2.0 shipped meaningful depth: four detail modes, frame deduplication, Whisper auto-chunking, explicit timestamp capture, and a pytest suite.
- Practical use cases in the README — bug diagnosis from screen recordings, launch-video hype stripping, playlist-to-notes — map directly to common creator and developer tasks.
Problem it solves
- Agents receive a YouTube link and either guess from the title or read an incomplete transcript that misses on-screen content.
- Screen recordings of bugs are unreadable to agents, forcing a human to scrub the video and describe the failing frame.
- Long update and launch videos bury the actual changes under intro material and marketing.
- Course and conference playlists become hours of passive watching instead of searchable notes.
- Native caption extraction is inconsistent across sources, leaving transcription gaps that break summarization.
How it works
- You paste a video plus a question. The source can be any URL yt-dlp supports (YouTube, Loom, TikTok, X, Instagram, and hundreds more) or a local file (.mp4, .mov, .mkv, .webm).
- yt-dlp checks captions first. At `transcript` detail, captioned URLs return without downloading video; otherwise the skill downloads only what the run needs.
- ffmpeg extracts frames at the chosen detail level. `efficient` decodes keyframes only with a cap of 50; `balanced` (the default) full-decodes to detect every scene cut with a cap of 100; `token-burner` keeps every scene-change frame uncapped.
- The transcript comes from one of two sources: native yt-dlp captions (free and instant), or a mono 16 kHz 64 kbps mp3 audio clip (~480 kB/min) shipped to Whisper — Groq's whisper-large-v3 (preferred) or OpenAI's whisper-1 as fallback.
- Frames and transcript are handed to Claude. The skill Reads every frame as a JPEG 512px wide and clamped to 1998px tall for Claude Read compatibility, so the model answers with both visual and audio context.
Architecture read: how the pieces fit
- Runtime is a self-contained `skills/watch/` package; SKILL.md resolves `$SKILL_DIR` from where it was Read instead of a Claude-Code-only variable, so script calls work on every host.
- External dependencies are yt-dlp for source handling and ffmpeg for frame extraction; both auto-install via `brew` on macOS on first run, and Linux/Windows print exact commands.
- Frame pipeline downscales each candidate to a 16×16 grayscale thumbnail and drops near-duplicates by mean per-pixel difference before the budget cap is applied.
- Transcription layer prefers yt-dlp native captions, then falls back to Whisper with auto-chunking for audio over the 25 MB upload cap; partial chunk failures are tolerated and only an all-chunk failure aborts transcription.
- Default detail is configurable via `WATCH_DETAIL` in `~/.config/watch/.env`; `--detail`, `--no-dedup`, `--timestamps`, `--no-whisper`, and `--max-frames` are the primary runtime knobs.
Try-it path: from install to first answer
- Claude Code: `/plugin marketplace add bradautomates/claude-video` then `/plugin install watch@claude-video`.
- Other Agent Skills hosts: `npx skills add bradautomates/claude-video -g` for a global install, or drop `-g` for a per-project scope.
- Smoke test: `/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?` to confirm both frame extraction and caption handling.
- Local-file test: `/watch bug-repro.mov what's going wrong?` to validate ffmpeg processing of a screen recording.
- On Windows, invoke scripts with `python` rather than `python3`, since `python3` resolves to the Microsoft Store stub on that platform.
Command surface and detail modes
- `--detail transcript` returns captions only with no frames; it is also the only mode that emits frames for `--timestamps`.
- `--detail efficient` decodes keyframes only, near-instant, capped at 50 frames.
- `--detail balanced` is the default; full-decodes to catch every scene cut across the whole video, capped at 100.
- `--detail token-burner` is scene-aware and uncapped, and is exempt from the long-video sparse-scan warning.
- `--timestamps T1,T2,…` grabs a frame at each absolute timestamp, reserved against the cap.
- `--no-whisper` disables transcription entirely for a frames-only run; `--no-dedup` disables the near-duplicate filter.
Who should pay attention?
Good fit if
- Claude Code users who want a marketplace-installed /watch command with auto-updates.
- Cursor, Codex, Copilot, and Gemini CLI users who need video reasoning inside their existing agent host.
- Creators and marketers analyzing competitor videos, ad creative, and launch drops for structure and hooks.
- Developers triaging screen-recorded bug reproductions without manually scrubbing the file.
- Learners converting long playlists and courses into searchable per-video notes.
Skip for now if
- Agents whose harness cannot execute SKILL.md skills or Read images in a Claude-compatible format.
- Air-gapped environments where yt-dlp, ffmpeg, and outbound video or Whisper API calls are blocked.
- Teams that require strict on-premise transcription with no external API dependency and have no Whisper backend.
- Use cases where title and existing transcripts already cover every question you need answered.
Risks and cautions
Core functionality depends on external binaries, agent-harness image support, and optional paid transcription APIs; setup is low-friction but the dependency surface is non-trivial.
- yt-dlp and ffmpeg must be present and correctly invoked; first-run auto-install is macOS-only via Homebrew, with manual steps elsewhere.
- Whisper fallback requires a Groq or OpenAI API key and sends audio off-device, which may violate data policies.
- Non-Claude hosts depend on the 0.2.0 self-contained package layout; prior versions were broken on those hosts.
- Token cost scales with frame count, and `token-burner` mode is explicitly uncapped for scene-change frames.
- Behavior on platforms with Microsoft Store `python3` stubs requires the documented `python` invocation workaround.
- MIT License, Copyright (c) 2026 Bradley Bonanno — permissive for commercial and private use.
- 0.1.3 hardened subprocess argv against option injection (issue #2): inserted `--` before the URL in yt-dlp argv and tightened `is_url` to reject `-`-prefixed sources and require a non-empty netloc.
- Resolved video and audio paths to absolute via `Path.resolve()` before passing them to ffmpeg or ffprobe, so relative paths starting with `-` cannot be misread as flags.
- Whisper fallback transmits a mono 16 kHz 64 kbps mp3 clip to Groq or OpenAI; review your provider and data-handling policy before using it on sensitive recordings.
- No claimed sandboxing of downloaded media; treat untrusted URLs the same as any yt-dlp input.
Alternatives to compare
| Approach | When to use | Trade-off |
|---|---|---|
yt-dlp (standalone) | You only need captions, metadata, or the media file itself and will inspect it manually. | Free, MIT-licensed. |
Whisper (OpenAI, open-source release) | You want local transcription without shipping audio to a third-party API. | Free to self-host; compute cost depends on hardware. |
| You need manual frame extraction, transcoding, or audio processing outside an agent loop. | Free, LGPL/GPL depending on build. | |
Built-in agent transcript paste | The source already has a complete, accurate transcript and no on-screen information matters. | Free. |
What this trend reveals
Video-aware bug triage pipelines
QA teams receive screen recordings daily; /watch can extract the failing frame, read on-screen state, and produce a draft issue without a human scrubbing the video.
Run `/watch bug-repro.mov what's going wrong?` on five recent recordings and compare the generated description against the filed ticket.
Competitive content teardown as data
Marketing teams can run /watch across a competitor's last 20 videos to extract opening hooks, structure, and on-screen claims into a structured spreadsheet.
Batch the channel's URLs at `--detail balanced`, then compare hook patterns against your own recent launches.
Course and playlist compression
Learners can convert a long playlist into per-video notes, preserving the on-screen diagrams that plain transcripts miss.
Point /watch at a course module with heavy slide content and confirm the notes reference specific visual frames, not just spoken words.
RepoDaily verdict
claude-video turns a real agent blind spot — video — into a one-line /watch command, with solid engineering choices around caption-first fetching, scene-aware frame extraction, and Whisper auto-chunking. The medium risk comes from yt-dlp and ffmpeg dependencies, optional paid transcription, and host-harness image support; for Claude Code and Agent Skills users who can accept those, it is a practical, well-scoped upgrade.