Skip to content
Get packs

Guide · Open source

How to use claude-video: install the watch skill and analyze videos

Updated · written with AI from the project's own documentation and checked against our catalogue data

claude-video is an open-source skill called watch, written in Python, that lets an AI agent review a video. You give it a YouTube-style URL or a local file, and it produces timestamped still frames and a transcript that the agent can read and answer questions about. This guide is for developers and careful users of Claude Code or Codex who want to install it and run a first video. After following it, you will have the skill installed, the required tools in place, and a timestamped summary of a short clip.

/watchbradautomates/claude-video · ★ 19.7k · MIT

Quick start

  1. 1Pick your install route. Choose one method that matches your app, such as Claude Code in a terminal or Codex's message box. Do not mix methods.
  2. 2Install the watch skill. Run the marketplace and install commands for your app, then restart or start a new session.
  3. 3Install prerequisites. Install Python 3.10 or newer, FFmpeg with ffprobe, and current yt-dlp. The skill does not bundle them.
  4. 4Check dependencies. Ask the agent to run the bundled setup.py check and report any missing tools.
  5. 5Share a short video. Put a short clip such as example.mp4 in a folder and open that folder as the agent's project.
  6. 6Ask for a timestamped summary. Paste the request into the agent's message box and read the timestamped result.
  7. 7Try a URL and optional keys. Test a public video URL with transcript detail, then add a Gemini or transcription key if you need them.

What the watch skill does

Watch is a skill (plugin) for AI agents such as Claude Code and Codex. It takes a video URL or a local file and turns it into timestamped still frames and a transcript. The agent then reads those outputs and answers your questions about the video.

It uses native captions when they exist. For videos without captions, it can fall back to local WhisperX or Groq/OpenAI transcription. It can also optionally send the whole video to a Google Gemini video model.

Choose the right install method for your app

Pick one installation method for your agent. Claude Chat and Cowork are not supported, so use Claude Desktop's Code session, Claude Code, or another Agent Skills host instead.

  • Claude Desktop, Code session: add the marketplace under Customize, then install Watch.
  • Codex: paste an install request into the message box, or use the native plugin commands if you have the Codex CLI.
  • Claude Code in VS Code: use the extension's plugin window and type /plugins.
  • Claude Code in a terminal: enter the plugin commands inside a session.
  • Cursor, Copilot or another local agent: use the Skills CLI.
/plugin marketplace add bradautomates/claude-video /plugin install watch@claude-video

Install Watch in Claude Code from a terminal

Start Claude Code with claude in your terminal. Then enter the two plugin commands inside the Claude Code session, one at a time. Follow the activation message, and if Watch is not available yet, start a new session. Type /watch and select /watch:watch from autocomplete.

If you are at an ordinary terminal prompt rather than inside a session, the README gives executable commands instead.

claude plugin marketplace add bradautomates/claude-video claude plugin install watch@claude-video

Install Watch for Codex or other local agents

For Codex, paste this into the message box in the desktop app, CLI or IDE extension, then start a new session and ask it to use watch. If the skill does not appear, restart Codex. You do not need Node or npm for this route.

For other Agent Skills hosts, install Node.js if needed, then run the Skills CLI command in your terminal. Select your agent when prompted and restart the agent afterward. Node and npm are needed for this installer only, not for Watch's Python runtime.

  • The IDE extension currently supports standalone skills, not plugins, so use the message-box route there.
Use $skill-installer to install the watch skill from: https://github.com/bradautomates/claude-video/tree/main/skills/watch

Prepare the required tools

Watch needs Python 3.10 or newer, FFmpeg with ffprobe, and a current yt-dlp. YouTube also needs a supported JavaScript runtime and EJS setup. Installing the skill does not bundle these programs, so install them yourself.

If you are unsure what is missing, ask your agent to run the bundled dependency check and list what it finds.

  • Python 3.10 or newer
  • FFmpeg and ffprobe
  • Current yt-dlp
  • A supported JavaScript runtime and EJS setup for YouTube
Use the watch skill's bundled setup.py to check dependencies in this session. Tell me which tools are missing

Run your first video without an API key

The no-key path is the simplest start. Give your agent access to a folder containing a short video such as example.mp4, and open that folder as the project. Then paste the request below into the agent's message box, replacing the filename with your own.

A successful run produces a timestamped visual summary. This first run needs no transcription key or local speech model. A local file with speech fallback disabled will not produce a speech transcript. The agent finds its bundled scripts itself, so you do not need to locate a plugin-cache folder.

Next, try a public video URL and ask for transcript detail. Native captions can be read without downloading the video, but URL access depends on the source and your session's network permissions.

  • Replace example.mp4 with your own file.
  • If the agent reports a missing program, install it and retry.
Use the watch skill on example.mp4 in the folder I shared. For setup, choose balanced detail and captions only (none). Summarize what is visible, with timestamps.

Use the Gemini path for the fastest result

If you have a free Google AI Studio key, Watch can hand the whole video, picture and sound, to Google's agentic video model and relay a timestamped answer. YouTube links need nothing else installed. Paste the key when the setup wizard asks, or open ~/.config/watch/.env and paste it after GEMINI_API_KEY= yourself.

Local files are uploaded to Google and deleted after the answer. If your video is private, use the local engine instead, which runs on your machine with ffmpeg and yt-dlp. Force it with --engine local.

  • Use Gemini for the quickest answer on public videos.
  • Use local for private videos or when you have no key.
  • Local WhisperX requires Watch v0.3.0 or later.
--engine local

What people use it for

  • Reviewing a screen recording of a bug and asking the agent where the problem appears, with timestamps.
  • Getting a timestamped summary of a tutorial video to share with a colleague or another agent.
  • Asking an agent questions about a public YouTube video that has captions.
  • Checking what is visible on screen in a short clip without watching it in full.

Frequently asked questions

Is claude-video free?

The project is released under the MIT licence. The README mentions a free Google AI Studio key for the Gemini path, but it does not give prices for the optional Groq or OpenAI transcription services, so check those providers directly.

Does claude-video work in Claude Chat?

No. The README says Watch does not work in Claude Chat or Cowork. Use Claude Code, Claude Desktop's Code session, Codex or another Agent Skills host.

What do I need installed before using it?

You need Python 3.10 or newer, FFmpeg with ffprobe, and a current yt-dlp. For YouTube, a supported JavaScript runtime and EJS setup are also needed. The skill does not bundle these programs.

Can I use it on private videos?

The README says local files are uploaded to Google when you use the Gemini path, so avoid that path for private videos. Use the local engine with --engine local, which extracts frames and transcripts on your machine.

Why does a local file give no speech transcript?

With speech fallback disabled, a local file will not produce a speech transcript. Enable a transcription fallback such as local WhisperX or a Groq or OpenAI key if you need the spoken words.

Are there alternatives to claude-video?

This analysis lists no comparable projects. If you need a different approach, you can check the Agent Skills ecosystem or other video tools, but this guide does not compare them.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Choose claude-video if you already use Claude Code or Codex, can install Python, FFmpeg and yt-dlp, and want your agent to review screen recordings or captioned public videos. Pick something else if you need Claude Chat or Cowork support, cannot install the required tools, or must keep private video files off Google's servers.

Install options & downloads