How to Set Up bradautomates/claude-video Locally: Complete Installation Guide

To set up bradautomates/claude-video locally, clone the repository, symlink the skills/watch/ directory to your AI host's skill folder, and execute the pre-flight setup script to install system dependencies.

The claude-video repository packages the /watch Agent Skill as a self-contained Python module that downloads videos, extracts frames using ffmpeg, and produces transcripts via native captions or OpenAI's Whisper API. Setting up bradautomates/claude-video locally involves preparing the skill environment, installing external binaries through setup.py, and optionally configuring cloud API credentials in ~/.config/watch/.env.

Prerequisites

Before installing, ensure your system meets these requirements:

• Python 3 (verified compatible version)
• Git for cloning the repository
• Bash environment for running setup scripts

The skills/watch/scripts/setup.py file will automatically handle ffmpeg and yt-dlp installation if they are missing.

Step-by-Step Installation

Clone the Repository

Start by cloning the official repository to your local machine:

git clone https://github.com/bradautomates/claude-video.git

This creates the claude-video/ directory containing the complete skill package.

Link the Skill to Your AI Host

The skill is self-contained within claude-video/skills/watch/. Create a symbolic link from this folder to your AI host's skill directory so the host can discover the slash command defined in skills/watch/SKILL.md.

For Claude Code:

ln -s "$(pwd)/claude-video/skills/watch" ~/.claude/skills/watch

For Codex:

ln -s "$(pwd)/claude-video/skills/watch" ~/.codex/skills/watch

For Cursor:

ln -s "$(pwd)/claude-video/skills/watch" ~/.cursor/skills/watch

Run the Pre-Flight Setup

Execute the setup script to verify dependencies and scaffold configuration files:

python3 claude-video/skills/watch/scripts/setup.py --check

This command invokes three critical functions from setup.py:

• Verifies or installs ffmpeg for frame extraction
• Verifies or installs yt-dlp for video downloads
• Creates the ~/.config/watch/ directory with a placeholder .env file

Configure API Keys for Whisper

If you plan to transcribe videos without native captions, configure Whisper API credentials. The skills/watch/scripts/config.py module reads from ~/.config/watch/.env at runtime:

GROQ_API_KEY=your-groq-key-here
OPENAI_API_KEY=your-openai-key-here

As implemented in skills/watch/scripts/whisper.py, the skill supports both Groq's whisper-large-v3 and OpenAI's whisper-1 endpoints using pure standard library HTTP requests.

Verify Your Installation

Test the installation by running the entry point directly against a video URL:

python3 claude-video/skills/watch/scripts/watch.py https://youtu.be/dQw4w9WgXcQ \
    --detail balanced --resolution 1024 --start 0:30 --end 1:00

This invokes the full workflow orchestrated by watch.py:

1. Argument parsing validates detail modes and frame budgets
2. Caption checking via fetch_captions in download.py determines if Whisper is needed
3. Metadata extraction using frames.get_metadata reads duration and resolution
4. Frame extraction through frames.extract_keyframes or frames.extract_scene_or_uniform handles deduplication and auto-FPS calculation
5. Transcript generation from VTT files (transcribe.py) or API calls (whisper.py)

Successful execution prints a markdown report to stdout listing extracted frame paths in /tmp/watch-XXXX/frames/ and transcript segments.

Optional: Build a Portable Skill Bundle

To create a distributable .skill file for uploading to claude.ai:

bash claude-video/skills/watch/scripts/build-skill.sh

This generates dist/watch.skill containing the entire skill package ready for distribution.

Summary

• Clone the repository using git clone https://github.com/bradautomates/claude-video.git
• Symlink claude-video/skills/watch/ to ~/.claude/skills/watch (or your host's equivalent directory)
• Run python3 claude-video/skills/watch/scripts/setup.py --check to install ffmpeg, yt-dlp, and scaffold config files
• Configure ~/.config/watch/.env with GROQ_API_KEY or OPENAI_API_KEY for Whisper transcription
• Execute watch.py directly or use the /watch slash command in your AI host to process videos

Frequently Asked Questions

What system dependencies does bradautomates/claude-video require?

The skill requires ffmpeg for frame extraction and yt-dlp for video downloads. The setup.py script automatically installs these if missing when you run it with the --check flag, so no manual system package manager commands are necessary.

Can I use bradautomates/claude-video without API keys?

Yes, if the target video has native captions in VTT format. The download.py wrapper checks for existing captions first; only if none exist does the workflow fall back to the Whisper API via whisper.py, which requires the Groq or OpenAI keys configured in ~/.config/watch/.env.

Where are extracted frames stored during processing?

The frames.py module writes extracted keyframes to temporary directories under /tmp/watch-XXXX/frames/ (where XXXX is a unique identifier). These paths are printed in the final markdown report and passed to the AI host for analysis.

How do I update the skill to the latest version?

Since the skill is symlinked to your local git repository, simply run git pull inside the claude-video directory. The changes take effect immediately for all AI hosts using the symlinked skill directory, including any updates to watch.py or helper modules.

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