# How to Watch a Video with Claude: The Complete /watch Command Guide > Learn the `/watch` command to download videos, extract frames, and generate AI-ready transcripts. Master Claude-Video for advanced video analysis. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: how-to-guide - Published: 2026-08-09 --- **The command to watch a video with Claude is `/watch`, a slash command provided by the Claude-Video repository that downloads video content, extracts visual frames with ffmpeg, and generates timestamped transcripts for AI analysis.** The `bradautomates/claude-video` repository adds powerful video comprehension capabilities to Claude through a self-contained Agent Skill. When you need to watch a video with Claude, the `/watch` command orchestrates the entire workflow from download to frame extraction, enabling the AI to answer detailed questions about visual content and dialogue. ## Installing the /watch Skill The skill is packaged as a single folder (`skills/watch/`) that integrates with multiple agent hosts. Choose the installation method that matches your Claude environment. ### Claude Code Installation For Claude Code users, install directly from the marketplace: ```bash /plugin marketplace add bradautomates/claude-video /plugin install watch@claude-video ``` ### Codex, Cursor, and Other Agent Hosts For Codex, Cursor, Copilot, or other Agent Skills hosts, use the Node.js installer: ```bash npx skills add bradautomates/claude-video -g ``` ### Manual Installation For development or custom setups, clone the repository and create a symbolic link: ```bash git clone https://github.com/bradautomates/claude-video.git ln -s "$(pwd)/claude-video/skills/watch" ~/.codex/skills/watch ``` ### First-Run Configuration On first execution, [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) performs a pre-flight check. This script automatically installs **ffmpeg** and **yt-dlp** if missing, and scaffolds the configuration directory at `~/.config/watch/.env` for storing Whisper API keys. ## Basic Usage: The /watch Command Syntax The fundamental pattern to watch a video with Claude combines the `/watch` command with a video source and optional natural language questions: ```text /watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark? ``` When invoked, [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) parses your arguments, downloads the video (or uses a local file path), extracts keyframes, obtains transcripts, and emits a markdown report that Claude can read and analyze. ## Advanced Parameters and Options The `/watch` command accepts several flags to control extraction fidelity, time ranges, and transcription sources. ### Time-Based Extraction (--start and --end) Focus analysis on specific segments using timestamp arguments: ```text /watch https://youtu.be/abc --start 2:15 --end 2:45 ``` The [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py) module filters caption data to your specified range, while [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) extracts only frames within those temporal boundaries. ### Detail Level Control (--detail) Manage the trade-off between processing speed and visual fidelity: ```text /watch https://youtu.be/dQw4w9WgXcQ --detail efficient # Fast keyframes, capped at 50 frames /watch https://youtu.be/dQw4w9WgXcQ --detail token-burner # Uncapped scene-aware extraction ``` The `--detail efficient` option uses `extract_keyframes` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) for rapid processing, while `token-burner` invokes `extract_scene_or_uniform` for maximum visual coverage. ### Transcription Backends (--whisper and --no-whisper) Control how speech is converted to text: ```text /watch video.mp4 --whisper openai # Force OpenAI Whisper API /watch video.mp4 --no-whisper # Disable audio transcription entirely ``` By default, [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) checks for existing captions via `fetch_captions` in [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) (which wraps yt-dlp), parses them with `parse_vtt`, and falls back to Whisper only when necessary. The [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) module handles API calls to Groq or OpenAI, loading credentials from `~/.config/watch/.env`. ### Frame Resolution (--resolution) Increase pixel dimensions when analyzing videos with on-screen text or fine details: ```text /watch video.mp4 --resolution 1024 ``` This parameter adjusts the extraction settings in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) before ffmpeg processes the video. ### Specific Timestamps (--timestamps) Request analysis at exact moments without processing the entire video: ```text /watch video.mp4 --detail transcript --timestamps 0:45,1:20,2:05 ``` This bypasses automatic frame selection and extracts only the specified cue frames. ## Technical Architecture and Source Code The `/watch` command operates through a harness-agnostic skill contract defined in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md). This file declares the command name, version, and required tools, resolving `SKILL_DIR` at runtime to ensure script portability across different agent hosts. The execution flow in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) orchestrates several specialized modules: - **[`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py)** – Wraps yt-dlp to fetch video metadata, download files, and retrieve native captions. - **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)** – Implements auto-FPS calculation, scene-change detection, keyframe extraction, and deduplication using ffmpeg. - **[`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py)** – Parses VTT caption files and filters content by time range. - **[`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py)** – Abstracts Whisper API clients for speech-to-text fallback. The skill maintains version parity across [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), [`.claude-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.claude-plugin/plugin.json), and [`.codex-plugin/plugin.json`](https://github.com/bradautomates/claude-video/blob/main/.codex-plugin/plugin.json) through the repository's release workflow. ## Summary - The primary command to watch a video with Claude is **`/watch`**, implemented in the `bradautomates/claude-video` repository. - The entry point [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) orchestrates download, frame extraction, and transcription workflows. - **yt-dlp** handles video acquisition while **ffmpeg** powers visual frame extraction via [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). - Transcripts derive from native captions when available, falling back to Whisper API calls managed by [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py). - Advanced flags like `--detail`, `--start`, and `--resolution` allow precise control over token consumption and analysis granularity. ## Frequently Asked Questions ### What is the exact command to watch a video with Claude? The exact command is `/watch` followed by your video URL or local file path. For example: `/watch https://youtu.be/example summary`. According to the `bradautomates/claude-video` source code, this invokes the Agent Skill defined in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) and executed by [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). ### Do I need to install ffmpeg and yt-dlp manually? No. The first time you run `/watch`, [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) automatically checks for these dependencies and installs them if missing. It also creates the `~/.config/watch/` directory for API key storage. ### Can I analyze local video files, or does it only work with URLs? The `/watch` command accepts both local file paths and remote URLs. The [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) module differentiates between the two, skipping the download step when a local path is provided while still processing frames and transcripts. ### How does the skill handle videos that lack captions? When native captions are unavailable, [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) falls back to the Whisper transcription service. The [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) module routes requests to either Groq or OpenAI based on your configuration in `~/.config/watch/.env`, ensuring speech content remains accessible for analysis.