How to Watch a Video with Claude: The Complete /watch Command Guide

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:

/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:

npx skills add bradautomates/claude-video -g

Manual Installation

For development or custom setups, clone the repository and create a symbolic link:

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 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:

/watch https://youtu.be/dQw4w9WgXcQ what happens at the 30 second mark?

When invoked, 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:

/watch https://youtu.be/abc --start 2:15 --end 2:45

The skills/watch/scripts/transcribe.py module filters caption data to your specified range, while 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:

/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 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:

/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 checks for existing captions via fetch_captions in 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 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:

/watch video.mp4 --resolution 1024

This parameter adjusts the extraction settings in skills/watch/scripts/frames.py before ffmpeg processes the video.

Specific Timestamps (--timestamps)

Request analysis at exact moments without processing the entire video:

/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. 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 orchestrates several specialized modules:

• skills/watch/scripts/download.py – Wraps yt-dlp to fetch video metadata, download files, and retrieve native captions.
• skills/watch/scripts/frames.py – Implements auto-FPS calculation, scene-change detection, keyframe extraction, and deduplication using ffmpeg.
• skills/watch/scripts/transcribe.py – Parses VTT caption files and filters content by time range.
• skills/watch/scripts/whisper.py – Abstracts Whisper API clients for speech-to-text fallback.

The skill maintains version parity across SKILL.md, .claude-plugin/plugin.json, and .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 orchestrates download, frame extraction, and transcription workflows.
• yt-dlp handles video acquisition while ffmpeg powers visual frame extraction via 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.
• 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 and executed by 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 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 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 falls back to the Whisper transcription service. The 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}