How Claude Video's Preflight Setup Checks and Installs Dependencies

Claude Video's preflight setup script detects missing system binaries (ffmpeg, ffprobe, yt-dlp), auto-installs them on macOS via Homebrew while providing platform-specific hints for Linux and Windows, scaffolds a configuration file at ~/.config/watch/.env, and verifies Whisper API keys before marking the setup complete.

The /watch skill in the bradautomates/claude-video repository relies on a comprehensive preflight routine to ensure all dependencies are present before processing video content. Located at skills/watch/scripts/setup.py, this Python script serves as the gatekeeper that validates system readiness, handles cross-platform installation logic, and manages API configuration without requiring elevated privileges.

What the Preflight Setup Validates

The setup.py script performs three essential tasks before allowing video processing to begin. First, it detects missing system binaries by scanning for ffmpeg, ffprobe, and yt-dlp using shutil.which. Second, it installs missing dependencies or provides exact installation commands for the user's operating system. Third, it scaffolds and finalizes user configuration by creating a .env file and verifying the presence of Whisper API keys.

Step-by-Step Implementation Details

Binary Detection with _check_binaries()

The core validation logic resides in _check_binaries(), which iterates through the REQUIRED_BINARIES list and uses Python's shutil.which to verify each tool is accessible in the system PATH.

# From skills/watch/scripts/setup.py

def _check_binaries():
    missing = []
    for binary in REQUIRED_BINARIES:
        if not shutil.which(binary):
            missing.append(binary)
    return missing

This function returns a list of missing binaries that drives all subsequent installation logic.

Platform-Specific Installation Logic

When binaries are missing, the script routes to platform-specific handlers. macOS receives automatic installation via the _install_macos() function, which verifies Homebrew presence and executes brew install ffmpeg yt-dlp. The mapping from binary names to package names uses the internal _brew_pkg abstraction.

For Linux and Windows, the script calls _install_hint_linux() or _install_hint_windows() to generate precise terminal commands rather than attempting automatic installation. Linux users receive apt or dnf suggestions for FFmpeg and pipx recommendations for yt-dlp, while Windows users get winget commands like winget install Gyan.FFmpeg.

Configuration Scaffolding with _scaffold_env()

The _scaffold_env() function creates ~/.config/watch/.env from a template defined in ENV_TEMPLATE. This operation is idempotent; re-running the setup never overwrites existing configuration files or API keys.

Once scaffolding completes, _write_setup_complete() appends SETUP_COMPLETE=true to the file, marking the installation as finalized for future preflight checks.

API Key Verification

The setup verifies Whisper API availability through _have_api_key(), which checks for GROQ_API_KEY or OPENAI_API_KEY in either the environment variables or the scaffolded .env file. The helper _read_env_key() reads the configuration file to detect existing keys without exposing them in logs.

Command-Line Interface Modes

The script exposes three distinct operational modes controlled by command-line arguments in the main() entry point.

--check Mode: Used by the /watch skill during regular operation. The cmd_check() function calls _status() and exits with code 0 if can_proceed is true. Non-zero exit codes indicate specific failure states: 2 for missing binaries, 3 for missing API key when setup is otherwise complete, and 4 for both binaries and API key missing.

--json Mode: Invoked via cmd_json(), this produces machine-readable status output including fields like status, can_proceed, missing_binaries, and platform.

Interactive Mode (default): The cmd_install() function provides the full setup experience, attempting auto-installation on macOS, displaying hints for other platforms, scaffolding the environment file, and guiding users through API key configuration.

Practical Usage Examples

Silent Preflight Check

Run this to verify readiness without interactive prompts, as the /watch skill does internally:

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

Exit codes:

• 0 - All binaries present and API key configured (or setup complete)
• 2 - Binaries missing
• 3 - No API key but setup marked complete
• 4 - Both binaries missing and no API key

Machine-Readable Status

For debugging or CI/CD pipelines:

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

Sample output:

{
  "status": "needs_install_and_key",
  "can_proceed": false,
  "first_run": true,
  "setup_complete": false,
  "missing_binaries": ["ffmpeg", "yt-dlp"],
  "whisper_backend": null,
  "has_api_key": false,
  "config_file": "/home/user/.config/watch/.env",
  "platform": "Linux"
}

First-Time Interactive Setup

For initial installation, run without flags:

python3 skills/watch/scripts/setup.py

This executes the full workflow: binary checks, macOS auto-installation (if applicable), .env scaffolding, and API key instructions. Once you add GROQ_API_KEY or OPENAI_API_KEY to ~/.config/watch/.env and re-run, the script confirms readiness with the message: [setup] ready. whisper backend: groq.

Summary

• skills/watch/scripts/setup.py serves as the central preflight mechanism for Claude Video's /watch skill.
• Binary detection uses shutil.which via _check_binaries() to locate ffmpeg, ffprobe, and yt-dlp.
• macOS auto-installation leverages Homebrew through _install_macos(), while Linux and Windows receive precise terminal commands via hint generators.
• Configuration management creates ~/.config/watch/.env idempotently using _scaffold_env() and tracks completion state with _write_setup_complete().
• API validation checks for GROQ_API_KEY or OPENAI_API_KEY through _have_api_key() before allowing processing.
• Exit codes (0, 2, 3, 4) enable programmatic consumption by the /watch skill and automation hooks.

Frequently Asked Questions

What system binaries does Claude Video require?

Claude Video requires three system binaries: FFmpeg (ffmpeg and ffprobe) for video processing, and yt-dlp for downloading video content from URLs. The _check_binaries() function in skills/watch/scripts/setup.py validates these are present in your system PATH before allowing any video operations.

Does the setup script require sudo or administrator privileges?

No. The preflight setup is designed for zero-sudo operation. On macOS, it uses Homebrew (which typically runs without sudo when properly configured), and on Linux/Windows it only prints installation hints rather than executing system-level commands. This safety design allows the script to run within Claude Code, Cursor, or other AI coding environments without elevation prompts.

How does the script handle API keys for Whisper transcription?

The script checks for GROQ_API_KEY (preferred for cost and speed) or OPENAI_API_KEY via _have_api_key() and _read_env_key(). If found in environment variables or ~/.config/watch/.env, the setup marks itself complete. If missing, the interactive installer displays specific instructions pointing to console.groq.com or platform.openai.com without terminating, allowing users to configure credentials after initial binary setup.

Can I run the preflight check without installing anything?

Yes. Use the --check flag to perform a read-only validation: python3 skills/watch/scripts/setup.py --check. This command exits silently with code 0 if ready, or returns specific error codes (2, 3, or 4) indicating what dependencies are missing, without triggering installation attempts or scaffolding new files.

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