Watch (claude-video) agent skill
A /watch skill that turns a video URL or local file into timestamped frames and a transcript, or hands it to Gemini, so the agent can answer questions about it.
with caveats
Well built and tested, but it needs Python, ffmpeg and a current yt-dlp on your machine, only Apple Silicon macOS installs are verified, and the cloud engines send video or audio to third parties.
broad access: pre-approves shell commands · makes network calls → security details
- Depth
- 4/5
- Last update
- 1 mo ago
- Installs
- —
- Stars
- 20K
- Forks
- 2.1K
- License
- MIT
What Watch (claude-video) does
With Watch installed, you can give the agent a video URL or a local file path and ask questions about what is in it. The skill runs a bundled Python script with two engines. The local engine downloads the video with yt-dlp, extracts auto-scaled frames with ffmpeg, and builds a transcript. It uses native captions first and falls back to local WhisperX, Groq's whisper-large-v3 or OpenAI's whisper-1. The agent then views the frames and answers from that evidence. If a GEMINI_API_KEY is set, the Gemini engine has Google's video model watch the whole video and return a timestamped answer for the agent to relay. The default auto setting picks Gemini when a key is found and local otherwise.
Detail levels run from transcript through efficient and balanced to token-burner, which samples on scene changes with no frame cap and warns above 250 frames. On first run, scripts/setup.py checks for binaries and asks which engine and fallback you want, then stores settings in ~/.config/watch/.env. Everything lives in one 17 KB SKILL.md with 11 helper scripts. A test suite uses synthesized FFmpeg media and runs in CI on Linux, macOS and Windows. Each run uses a disposable directory that is cleaned up afterward.
Good for
- Asking questions about a YouTube video or screen recording
- Pulling timestamped evidence from a demo, talk or bug video
- Claude Code or Codex users on a local machine
Not for
- Claude Chat or Cowork, which the README says are not supported
- Videos you cannot send to Google, Groq or OpenAI, unless you stick to the local engine and WhisperX
What's inside depth 4/5
One 17 KB SKILL.md backed by 11 helper scripts, a setup wizard, a test suite and cross-platform CI, though there are no evals of the agent's answers.
- Skills
- 1
- Reference docs
- 0
- Scripts
- 11
- Tests / evals
- 0
- Templates
- 0
- Avg SKILL.md
- 16.8 KB
Counted from the repository file tree. How we score depth.
Dependencies and costs
- Python 3.10+
- ffmpeg and ffprobe
- yt-dlp (latest release only)
- Deno (listed in the Windows install recipe)
- Optional: Google AI Studio GEMINI_API_KEY for the Gemini engine
- Optional: GROQ_API_KEY or OPENAI_API_KEY for cloud transcription
- Optional: local WhisperX, which runs in a separate Python 3.12 environment and downloads models
- Telemetry: none found. The WhisperX helper sets PYANNOTE_METRICS_ENABLED=0 for its subprocess. The Gemini engine uploads the video to Google, and the groq/openai backends send audio to those providers. The local engine never contacts Google.
Security review
Security: Broad accessThis skill asks for more access than most, or sends data to another service. That is usually a design choice rather than bad intent, but you should know before you install it.
- Pre-approves broad shell commandsFrontmatter allowed-tools pre-approves unrestricted Bash.skills/watch/SKILL.md:5
This skill downloads videos with yt-dlp and extracts frames and transcripts locally with ffmpeg. If a Gemini key is configured (the default 'auto' engine picks it up from your environment or a .env file), videos are uploaded to Google; with Groq or OpenAI selected, extracted audio is sent to that provider. Its SKILL.md pre-approves unrestricted Bash, and optional WhisperX setup installs uv via a downloaded install script plus about 1.5 GB of packages and models under ~/.cache.
Worth knowing
- Makes network requestsWith the gemini engine, YouTube URLs are sent to Google, and local or downloaded videos are uploaded to the Gemini Files API, then deleted after the answer.skills/watch/scripts/gemini.py:20
- Makes network requestsWith the groq or openai backend, extracted audio is uploaded to that provider's transcription endpoint.skills/watch/scripts/whisper.py:30
- Makes network requestsRuns yt-dlp to fetch metadata, captions and media from the video's source site.skills/watch/scripts/download.py:41
- Needs an API key for its own serviceGEMINI_API_KEY, GROQ_API_KEY and OPENAI_API_KEY are read from env, ~/.config/watch/.env or cwd .env, and each is sent only to its own provider.skills/watch/scripts/config.py:107
- browser_session_optional--cookies-from-browser / WATCH_COOKIES_FROM_BROWSER passes a browser cookie selector to yt-dlp, only when the user sets it.skills/watch/scripts/download.py:33
- installs_hooksA documented SessionStart hook runs setup.py --check and prints a setup advisory.hooks/hooks.json:3
- Installs packages or toolsSetup can brew-install ffmpeg/yt-dlp/uv and create a WhisperX venv with pinned torch 2.8.0 and whisperx 3.8.6 plus model downloads.skills/watch/scripts/setup.py:99
- Installs with curl | shThe WhisperX installer downloads and runs the uv install script from astral.sh (curl then sh on Linux; irm | iex on Windows).skills/watch/scripts/setup.py:258
- Changes files outside your projectWrites settings and API keys to ~/.config/watch/.env and creates a managed venv at ~/.cache/watch/whisperx-venv.skills/watch/scripts/config.py:12
- Relies on a CLI or package we could not reviewRelies on yt-dlp and, optionally, the whisperx CLI and uv, whose source is not in this repo.skills/watch/scripts/download.py:41
What we checked
The repository (51 files) on Nov 1, 2026. Not a full review: we read 20 of 35 code files; it relies on code outside the repository: yt-dlp (external CLI used for all URL downloads); pip package whisperx==3.8.6 and its dependencies (torch, torchaudio) installed by setup.py; uv install script served from https://astral.sh/uv/install.sh (and install.ps1).
NVIDIA SkillSpector static scan: 76 pattern hits (Dangerous Code Execution 20, Data Exfiltration 19, Privilege Escalation 17, MCP Rug Pull 6, Agent Snooping 5, Excessive Agency 5). The env-harvesting and .env hits are the config loader for the skill's own API keys and test fixtures that isolate the environment. The browser-cookie YARA hits are the documented opt-in --cookies-from-browser flag passed to yt-dlp. The 'upload session' and subprocess hits are the Gemini Files API upload and local ffmpeg/WhisperX invocations; sudo appears only in CI and printed install hints.
A review, not a certification. Skills change after we check them — read the files before installing.
License
MIT, commercial use allowed.
Can it run unattended?
Not really. It is an on-demand tool you call for one video at a time, and first-run setup asks you interactive questions about engine and transcription.
FAQ
What is claude-video / the /watch skill?
It is an agent skill by bradautomates that lets Claude Code, Codex and other Agent Skills hosts work with video. It turns a URL or local file into timestamped frames and a transcript, or, with a Gemini key, has Google's video model watch the full video and report back.
How do I install Watch?
In Claude Code for VS Code, run /plugins, add the marketplace bradautomates/claude-video and install watch. In Claude Desktop, add the repo URL as a marketplace under Customize > Plugins, install Watch, and use a Code session. In Codex, ask it to use $skill-installer with the skills/watch URL, or run codex plugin marketplace add bradautomates/claude-video and codex plugin add watch@claude-video.
Do I need an API key?
No. The local engine works with captions, frames and optionally local WhisperX, none of which need a key. A free Google AI Studio key enables the Gemini engine, and Groq or OpenAI keys enable cloud transcription for videos without captions.
Does Watch work in Claude Chat or Cowork?
No. The README says Watch does not work in Claude Chat or Cowork. Cowork runs it in a cloud environment where the GEMINI_API_KEY does not persist between tasks. Use a Claude Code session instead.
Is Watch safe to install?
We found no hidden network calls or credential harvesting. The script reads API keys from the environment or ~/.config/watch/.env and, per the README, sends them only as request headers and never logs them. Know that the Gemini and cloud Whisper options upload your video or audio to those providers, and that the browser-cookie option lets yt-dlp read your browser's cookie store.
Does it run on Windows and Linux?
The README gives recipes for macOS 13+, Ubuntu 22.04+ and Windows 10+ with PowerShell, and CI tests run on all three. It also says only Apple Silicon macOS installs are verified, and Intel macOS, Linux and Windows installs are untested.