What the Claude Video Setup.py Preflight Check Validates

The setup.py preflight check validates that required video processing binaries are installed, a Whisper API key is configured, and the first-run setup is complete, ensuring the /watch skill can operate without runtime errors or user spam.

The bradautomates/claude-video repository includes a robust environment validation system within skills/watch/scripts/setup.py. When invoked with the --check flag, this preflight verification ensures that the /watch skill has access to necessary video processing tools and transcription APIs before execution. By evaluating binary availability and authentication credentials upfront, the script prevents runtime failures and unnecessary prompts.

Three Critical Validation Checks

The preflight logic, implemented in the cmd_check function, evaluates three specific criteria to determine if the environment is ready for video processing operations.

Required Binary Availability

The check ensures that three essential command-line tools are present on the system: ffmpeg, ffprobe, and yt-dlp.

In skills/watch/scripts/setup.py, the _check_binaries() function calls _which() for each binary to verify installation. If any are missing, the function returns a list of absent executables that gets reported to the user. According to the source code at lines 66–68, this validation is the first technical hurdle the preflight must clear before the skill can function.

Whisper API Key Configuration

The script verifies that at least one transcription API key is available to support Whisper speech-to-text processing.

The helper _have_api_key() (lines 16–22) searches for either GROQ_API_KEY or OPENAI_API_KEY in the environment variables or the user configuration file located at ~/.config/watch/.env. This function returns a boolean indicating whether a valid key was found and which backend is available for transcription services.

First-Run Completion Status

The preflight distinguishes between new users and those who have completed the installation process.

The is_first_run() function (lines 24–27) checks for the SETUP_COMPLETE=true flag inside ~/.config/watch/.env. When this flag is set, the user has already run the installer once, allowing the skill to proceed in a degraded mode (frames-only output) even without a Whisper API key.

Status Classification System

The _status() function aggregates validation results into one of four discrete states that determine whether the /watch skill can safely execute:

• ready – All binaries are present and a Whisper API key is available.
• needs_install_and_key – Binaries are missing and no Whisper API key is set.
• needs_install – Binaries are missing but a Whisper API key exists.
• needs_key – Binaries are present but a Whisper API key is missing and the user has not completed the first-run setup.

The boolean can_proceed (used by cmd_check at lines 42–46) evaluates to True only when both conditions are satisfied: no missing binaries and either a Whisper API key is present or the user has already completed the first-run setup.

Exit Codes and Error Handling

When the preflight check fails, cmd_check prints a concise error to stderr and exits with a distinct code for programmatic handling:

• 0 – All requirements satisfied; silent success.
• 2 – One or more required binaries are missing.
• 3 – No Whisper API key and the user has not completed first-run setup.
• 4 – Both binaries are missing and no API key is set.

Running the Preflight Check

Execute the silent preflight validation to verify your environment:

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

For machine-readable output suitable for scripting or automation:

python3 skills/watch/scripts/setup.py --json

When binaries are missing, the script outputs a specific error message to stderr:

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

Summary

• The setup.py preflight check validates three requirements: binary availability, API key presence, and first-run completion status.
• Required binaries include ffmpeg, ffprobe, and yt-dlp, verified via _check_binaries() and _which().
• The script searches for GROQ_API_KEY or OPENAI_API_KEY in environment variables or ~/.config/watch/.env using _have_api_key().
• The can_proceed boolean logic determines execution permission based on binary presence and either API key availability or the SETUP_COMPLETE=true flag.
• Exit codes 2, 3, and 4 provide specific failure reasons for missing binaries, missing keys, or both, respectively.

Frequently Asked Questions

What binaries does the setup.py preflight check look for?

The check validates the presence of ffmpeg, ffprobe, and yt-dlp on the system. These tools handle video processing, metadata extraction, and stream downloading respectively. The _check_binaries() function in skills/watch/scripts/setup.py verifies each binary using the _which() helper.

Can I use the /watch skill without a Whisper API key?

Yes, but only if you have completed the first-run setup. The is_first_run() function checks for SETUP_COMPLETE=true in ~/.config/watch/.env. If this flag is set, the skill can proceed with frames-only output even without a GROQ_API_KEY or OPENAI_API_KEY, though transcription features will be unavailable.

What exit code indicates missing binaries only?

Exit code 2 indicates that one or more required binaries are missing while API key configuration may be valid. This allows automated deployment scripts to distinguish between environment setup issues (missing dependencies) and configuration issues (missing credentials).

Where does the preflight check look for API keys?

The _have_api_key() function searches for GROQ_API_KEY or OPENAI_API_KEY in the current environment variables or within the user configuration file at ~/.config/watch/.env. The function returns a boolean indicating whether at least one valid transcription backend is available for the Whisper speech-to-text processing.

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