# What Checks Does the claude-video Setup/Preflight Process Perform Before Running 'watch'?

> Discover the five crucial checks claude-video's setup/preflight process performs before running watch. Ensure binaries ffmpeg ffprobe yt-dlp Whisper API key setup completion file permissions and config sanity.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-04

---

**The claude-video preflight validates five critical conditions: required binaries (ffmpeg, ffprobe, yt-dlp), Whisper API key availability, setup completion status, file permissions, and configuration sanity.**

The `claude-video` repository by bradautomates implements a robust preflight system to ensure the `/watch` skill operates reliably. Before processing any video, the setup script at **[`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py)** executes a series of environment checks that gate access to the core functionality. This article examines each validation step, its source implementation, and the exit codes used to signal readiness states.

## Required Binaries Check

The preflight first verifies that three external dependencies are present on the host system.

**`_check_binaries()`** scans the PATH for:
- **`ffmpeg`** – video/audio processing engine
- **`ffprobe`** – media metadata extraction
- **`yt-dlp`** – YouTube and streaming platform downloader

This function returns a list of missing binaries. If any are absent, the script provides platform-specific installation hints (Homebrew for macOS, apt for Linux, winget for Windows)【/skills/watch/scripts/setup.py#L66-L68】.

```bash

# Check binary availability manually

python3 -m skills.watch.scripts.setup --check

# Exit code 2 indicates missing binaries

```

## Whisper API Key Validation

Transcription capabilities require a valid API key for OpenAI's Whisper or Groq's hosted equivalent.

**`_have_api_key()`** implements a preference hierarchy:
1. **`GROQ_API_KEY`** environment variable (preferred)
2. **`OPENAI_API_KEY`** environment variable (fallback)
3. `GROQ_API_KEY` or `OPENAI_API_KEY` in `~/.config/watch/.env`【/skills/watch/scripts/setup.py#L16-L21】

The check permits operation without a key only when `SETUP_COMPLETE=true` is already set, preventing first-run attempts without configuration.

## Setup Completion Detection

The preflight distinguishes between uninitialized environments and ready-to-run states.

**`is_first_run()`** reads `~/.config/watch/.env` via `_read_env_key()` to locate the `SETUP_COMPLETE` flag【/skills/watch/scripts/setup.py#L24-L27】. This boolean:
- Suppresses first-run wizard prompts on subsequent invocations
- Allows bypass of API key requirements for users who intentionally skip transcription

## File Permission Security Warning

Credential exposure is mitigated through proactive permission scanning.

**`_check_file_permissions()`** examines the `.env` file and emits a one-time warning if it detects world-readable or group-readable bits【/skills/watch/scripts/setup.py#L73-L88】. This runs non-blocking—execution continues, but users are alerted to potential secret leakage.

The warning pattern follows security best practices for credential storage without halting legitimate workflows.

## Configuration Sanity Check

The final validation loads user preferences without enforcing constraints.

**`_status()`** calls `get_config()` from **[`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py)** to retrieve the `watch_detail` setting【/skills/watch/scripts/setup.py#L44-L56】. This value controls transcription verbosity and is included in JSON status output for observability.

Unlike preceding checks, invalid configurations here don't block execution—they're reported for debugging purposes.

## Exit Codes and Decision Logic

The **`cmd_check()`** entry point aggregates all validations into actionable exit states:

| Exit Code | Condition | Resolution Path |
|-----------|-----------|---------------|
| **0** | All binaries present AND (API key exists OR setup complete) | Ready to run `/watch` |
| **2** | One or more binaries missing | Install ffmpeg, ffprobe, yt-dlp |
| **3** | First run without API key | Run installer, add GROQ_API_KEY or OPENAI_API_KEY |
| **4** | Binaries missing AND no API key | Complete full setup workflow |

For programmatic integration, **`cmd_json()`** exports structured status from `_status()`【/skills/watch/scripts/setup.py#L94-L98】:

```bash

# Machine-readable status inspection

python3 -m skills.watch.scripts.setup --json | jq .

```

## Running the Preflight Manually

Interactive setup and silent checks follow distinct patterns:

```bash

# Full interactive installation (creates ~/.config/watch/.env)

python3 -m skills.watch.scripts.setup

# Silent readiness probe (exit code only)

python3 -m skills.watch.scripts.setup --check

# Verbose status for CI/CD pipelines

python3 -m skills.watch.scripts.setup --json

```

Typical failure output guides remediation:

```

[watch] setup incomplete (missing binaries: ffmpeg, yt-dlp; no Whisper API key (GROQ_API_KEY or OPENAI_API_KEY)). Run: python3 /path/to/setup.py

```

## Summary

The claude-video preflight process enforces five sequential checks before permitting `/watch` execution:

- **Binary dependencies** – ffmpeg, ffprobe, yt-dlp must be PATH-accessible
- **API credentials** – GROQ_API_KEY or OPENAI_API_KEY required for first run
- **Setup state** – SETUP_COMPLETE flag silences initialization prompts
- **Permission hygiene** – .env file readability warnings protect secrets
- **Configuration load** – watch_detail preference retrieved for operational context

Each check maps to specific source locations in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) with deterministic exit codes for automation compatibility.

## Frequently Asked Questions

### What happens if yt-dlp is installed but ffmpeg is missing?

The preflight returns **exit code 2** and reports `ffmpeg` specifically in the missing binaries list. According to `claude-video` source code, all three binaries must pass validation simultaneously—partial installation doesn't satisfy requirements.

### Can I run `/watch` without a Whisper API key?

Only after marking setup complete. The `_have_api_key()` check permits bypass when `SETUP_COMPLETE=true` exists in `~/.config/watch/.env`. Without this flag, first-run detection triggers exit code 3.

### Where does the preflight look for API keys?

Four locations in order: `GROQ_API_KEY` environment variable, `OPENAI_API_KEY` environment variable, then both keys in `~/.config/watch/.env` as implemented in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) lines 16-21.

### Why does the setup script warn about file permissions?

The `_check_file_permissions()` function at lines 73-88 detects world-readable or group-readable `.env` files to prevent credential exposure in multi-user environments. This warning fires once per process without blocking execution.