How the Claude Video `setup.py` Preflight Check Validates Your Environment

The cmd_check function in skills/watch/scripts/setup.py validates that required binaries (ffmpeg, ffprobe, yt-dlp) and Whisper API keys are present before the /watch skill executes, returning specific exit codes (0, 2, 3, or 4) to signal readiness or specific deficiencies.

Before the Claude Video /watch skill processes any video, it runs a preflight check to ensure the environment is properly configured. The setup.py preflight check function in Claude Video performs this validation by examining system dependencies and credentials without modifying any files. This check lives in skills/watch/scripts/setup.py and is designed to be idempotent, allowing it to run silently on every invocation while only alerting users when action is required.

The Core Logic: cmd_check and _status()

The heart of the preflight validation resides in the cmd_check function, which delegates state gathering to the internal _status() helper. Together, these functions determine whether the environment is ready for video processing according to the bradautomates/claude-video source code.

Collecting the Status Snapshot

The _status() function aggregates four critical data points by calling specialized helpers:

• Binary verification: _check_binaries() scans the system for ffmpeg, ffprobe, and yt-dlp executables.
• API key presence: _have_api_key() checks for GROQ_API_KEY or OPENAI_API_KEY environment variables required for Whisper transcription.
• Installation history: is_first_run() verifies whether SETUP_COMPLETE=true exists in the configuration.
• User configuration: get_config() from config.py retrieves platform details and the user-defined watch detail level (cfg["detail"]).

Determining Environment State

Based on the snapshot, _status() derives one of four high-level states:

• ready: All binaries present and a Whisper API key is configured.
• needs_key: Binaries exist but no API key is set (indicates a first run).
• needs_install: Binaries are missing but a key is present (indicates a failed or incomplete installation).
• needs_install_and_key: Both binaries and API keys are absent.

The function also computes can_proceed, which evaluates to true only when binaries exist and either a valid API key is present or the installer has previously completed (SETUP_COMPLETE=true).

Exit Code Strategy

The cmd_check function translates the status snapshot into actionable exit codes:

• Exit 0: can_proceed is true. The environment is ready and /watch can execute silently.
• Exit 2: Binaries are missing but an API key exists (or a previous installation failed).
• Exit 3: Binaries are present but no API key is configured, and the installer has never completed (genuine first-run scenario).
• Exit 4: Both binaries and an API key are missing.

When returning a non-zero code, cmd_check prints a concise, actionable message to stderr (e.g., "missing binaries: ffmpeg, yt-dlp; no Whisper API key").

Idempotent Safety Design

Because cmd_check only inspects state and never writes configuration files or modifies the environment, it remains completely idempotent. This design allows the watch skill to invoke the preflight check on every turn without generating repetitive "setup complete" messages. The function acts as a read-only gatekeeper, ensuring users only receive warnings when dependencies are genuinely missing.

Running the Preflight Check

You can execute the preflight check directly from the command line or integrate it into Python scripts.

To verify your environment from the terminal:

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

# Exit 0 indicates success; exits 2-4 trigger stderr warnings with specific deficiency details

To invoke the check programmatically from another Python script:

import subprocess
import sys

result = subprocess.run(
    [sys.executable, "-m", "skills.watch.scripts.setup", "--check"],
    capture_output=True,
    text=True,
)

if result.returncode == 0:
    print("✅ Environment ready for Claude Video processing")
else:
    print(f"⚠️ Setup needed: {result.stderr.strip()}")
    sys.exit(result.returncode)

Integration with the Watch Skill

The preflight check integrates directly with the video processing pipeline. In skills/watch/scripts/watch.py, the entry point for the /watch skill invokes setup.cmd_check() before processing any video URL. This ensures that Claude Video only attempts transcription when all required binaries are available and a Whisper backend is properly configured, preventing mid-process failures due to missing dependencies.

Summary

• The cmd_check function in skills/watch/scripts/setup.py serves as the gatekeeper for the Claude Video /watch skill.
• It validates presence of ffmpeg, ffprobe, yt-dlp, and Whisper API keys (GROQ_API_KEY or OPENAI_API_KEY).
• Returns exit codes 0, 2, 3, or 4 to indicate specific readiness states or deficiencies.
• Uses can_proceed logic to distinguish between ready environments and those requiring setup.
• Designed to be idempotent and safe for repeated execution without side effects.

Frequently Asked Questions

What exit codes does the Claude Video setup.py preflight check return?

The preflight check returns four specific exit codes. Exit 0 indicates the environment is ready. Exit 2 signals missing binaries (ffmpeg, ffprobe, or yt-dlp). Exit 3 indicates binaries are present but no Whisper API key is configured. Exit 4 means both binaries and API keys are missing.

Which binaries does the preflight check verify?

According to the source code in skills/watch/scripts/setup.py, the _check_binaries() function verifies the presence of three required executables: ffmpeg, ffprobe, and yt-dlp. These tools handle video download, processing, and metadata extraction for the Claude Video workflow.

How does the preflight check determine if it's a first run?

The check uses the is_first_run() helper to look for SETUP_COMPLETE=true in the configuration. If this flag is absent and no API key is present, the _status() function classifies the state as needs_key or needs_install_and_key, triggering exit code 3 or 4 respectively.

Can I run the setup.py preflight check multiple times safely?

Yes. The cmd_check function is read-only and never modifies files or environment variables. This idempotent design allows it to run repeatedly without side effects, making it safe to invoke before every video processing operation in the Claude Video workflow.

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