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

> Set up bradautomates/claude-video locally with this installation guide. Clone the repo, symlink the skills directory, and run the setup script to get started quickly.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: getting-started
- Published: 2026-07-15

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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:

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md).

**For Claude Code:**

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

```

**For Codex:**

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

```

**For Cursor:**

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

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

```

This command invokes three critical functions from [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) module reads from `~/.config/watch/.env` at runtime:

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

```

As implemented in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/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:

```bash
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`](https://github.com/bradautomates/claude-video/blob/main/watch.py):
1. **Argument parsing** validates detail modes and frame budgets
2. **Caption checking** via `fetch_captions` in [`download.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py)) or API calls ([`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/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
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/download.py) wrapper checks for existing captions first; only if none exist does the workflow fall back to the Whisper API via [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py), which requires the Groq or OpenAI keys configured in `~/.config/watch/.env`.

### Where are extracted frames stored during processing?

The [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) or helper modules.