Un agente di coding legge file, esegue comandi, guarda screenshot. Un video, no. La skill Watch del progetto claude-video colma questo buco: scarica il video, ne estrae i fotogrammi e la trascrizione con i timestamp e li consegna all'agente, che può così rispondere su «cosa succede al minuto 2:15».
Gli usi concreti sono più di quanti sembri: analizzare la registrazione di un bug riprodotto, ricavare i passaggi di un tutorial, estrarre i punti chiave di una demo o di una call registrata, documentare un flusso mostrato a video.
Dove funziona (e dove no)
Funziona in Claude Code — da terminale e da VS Code — in Claude Desktop, in Codex (desktop, CLI, estensione IDE), in Cursor e in altri agenti locali. Non funziona nella chat di Claude né nelle app browser: servono accesso al filesystem e strumenti locali.
Installazione in Claude Code
claude plugin marketplace add bradautomates/claude-video
claude plugin install watch@claude-videoPer altri agenti compatibili con la CLI delle skill:
npx skills add bradautomates/claude-video -g --skill watchPer Codex:
codex plugin marketplace add bradautomates/claude-video
codex plugin add watch@claude-videoDipendenze
Servono Python 3.10+, FFmpeg/ffprobe e una versione aggiornata di yt-dlp. Per i video YouTube serve anche un runtime JavaScript (Deno).
# Windows
winget install --id Gyan.FFmpeg --exact
winget install --id yt-dlp.yt-dlp --exact
winget install --id DenoLand.Deno --exact
# macOS
brew install python ffmpeg yt-dlp
# Ubuntu/Debian
sudo apt install python3 ffmpeg pipx
pipx install "yt-dlp[default,curl-cffi]"
pipx ensurepathLa skill include uno script di diagnostica: si può chiedere all'agente di eseguire setup.py --check per sapere cosa manca.
I due motori
| Motore | Requisiti | Nota |
|---|---|---|
gemini | GEMINI_API_KEY (gratuita da Google AI Studio) | Più veloce; i video YouTube vanno direttamente a Google, gli altri file vengono caricati sulle Files API e poi cancellati |
local | Nessuna API key | Fotogrammi e trascrizione elaborati sul proprio computer |
Il default è auto. Vale la pena essere consapevoli della differenza: con il motore cloud il contenuto del video esce dalla macchina. Per materiale riservato — registrazioni interne, dati di clienti — la modalità locale è l'unica scelta sensata.
Comandi
/watch video.mp4 --start 2:15 --end 2:45
/watch video.mp4 --detail efficient --max-frames 30
/watch video.mp4 --detail transcript --timestamps 1:05,2:30
/watch https://youtube.com/watch?v=... --engine gemini
/watch video.mp4 --sub-lang it
/watch video.mp4 --resolution 1024Livelli di dettaglio
| Livello | Comportamento | Tetto fotogrammi |
|---|---|---|
transcript | Solo trascrizione | — |
efficient | Keyframe rapidi | 50 |
balanced | Cambi di scena (default) | 100 |
token-burner | Cambi di scena senza limite | — |
Il nome dell'ultimo livello è già un avvertimento: i fotogrammi sono immagini e le immagini costano token. Su un video lungo conviene partire da efficient e restringere l'intervallo con --start/--end.
Trascrizione
Watch legge prima i sottotitoli nativi, se ci sono; altrimenti ricorre a un backend di trascrizione, scelto al primo avvio: whisperx in locale (nessuna API key, circa 3 GB di disco e 8 GB di RAM), oppure Groq o OpenAI via cloud, oppure nessuno. La configurazione persiste in ~/.config/watch/.env o in un .env nella cartella corrente:
GEMINI_API_KEY=la_tua_chiave
WATCH_ENGINE=auto
WATCH_DETAIL=balanced
WATCH_SUB_LANG=it
WATCH_WHISPER_BACKEND=whisperxSu sistemi POSIX conviene dare al file permessi 0600. Licenza MIT.