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

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 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】.

# 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 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】:

# Machine-readable status inspection

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

Running the Preflight Manually

Interactive setup and silent checks follow distinct patterns:

# 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 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 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.

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