How the Initial Setup and Preflight Check Operate on the First Run in Claude-Video

The /watch skill uses skills/watch/scripts/setup.py to detect first-run state via a SETUP_COMPLETE flag in ~/.config/watch/.env, scaffold configuration files, verify required binaries (ffmpeg, ffprobe, yt-dlp), and validate Whisper API keys before allowing video processing to begin.

The bradautomates/claude-video repository provides a video analysis skill for Claude Code that requires specific external dependencies and API credentials. Understanding how the initial setup and preflight check operate on the first run ensures smooth deployment across macOS, Linux, and Windows environments. The bootstrap mechanism centers on a single Python script that handles everything from binary installation to persistent configuration management.

Detecting First-Run State and Scaffolding Configuration

The setup process begins with the is_first_run() function in skills/watch/scripts/setup.py (lines 24-27), which checks for SETUP_COMPLETE=true in ~/.config/watch/.env. If this marker is absent or not set to "true", the script triggers the full installation flow.

The _scaffold_env() function (lines 29-39) creates the configuration directory and a minimal .env file with placeholder comments for GROQ_API_KEY and OPENAI_API_KEY. This file receives chmod 600 permissions to ensure API credentials remain private.

# Verify first-run status via JSON output

$ python3 skills/watch/scripts/setup.py --json | jq .first_run
true

Verifying System Dependencies and API Credentials

Before the /watch skill can process video, the setup script validates three external binaries through _check_binaries() (lines 66-68). The script searches the system $PATH for ffmpeg, ffprobe, and yt-dlp, recording any missing executables for later installation.

Simultaneously, _have_api_key() (lines 16-21) inspects the environment for either GROQ_API_KEY or OPENAI_API_KEY. The presence of either key enables Whisper transcription capabilities; otherwise, the skill operates in frame-only mode.

Silent Preflight vs. Interactive Installation Modes

The setup script operates in two distinct modes depending on invocation arguments. When called with --check, the cmd_check() function (lines 59-71) performs a silent preflight validation used internally by the /watch command.

This mode calls _status() to aggregate binary and API key checks into a readiness snapshot. If _status()["can_proceed"] returns True, the script exits with code 0 and no output. Missing components trigger specific exit codes: 2 for missing binaries, 3 for missing API keys, or 4 for both deficiencies, with actionable error messages directed to stderr.

Running the Interactive Installer

Without arguments, cmd_install() (lines 99-133) executes the full setup wizard. On macOS, this function automatically installs missing binaries via Homebrew; Linux and Windows receive manual installation instructions. The installer prompts users to add a Whisper API key before completing the setup.

# First-run: interactive installer

$ python3 skills/watch/scripts/setup.py
[setup] created config: /home/you/.config/watch/.env
[setup] one step left: add a Whisper API key.

# Add key and re-run to complete setup

$ echo "GROQ_API_KEY=your_key" >> ~/.config/watch/.env
$ python3 skills/watch/scripts/setup.py
[setup] ready. whisper backend: groq
[setup] installed dependencies; /watch is fully set up.

Persisting Setup Completion

Once binary checks pass and an API key is detected, _write_setup_complete() (lines 42-50) appends SETUP_COMPLETE=true to ~/.config/watch/.env. Future invocations detect this flag and skip the interactive installer, allowing subsequent /watch calls to proceed directly to the silent --check validation.

# Silent preflight (used internally by /watch)

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

# exits 0 with no output → /watch can proceed

Summary

• The setup script detects first-run state by checking for SETUP_COMPLETE=true in ~/.config/watch/.env using is_first_run().
• Required binaries (ffmpeg, ffprobe, yt-dlp) are verified via _check_binaries(), with macOS systems receiving automatic Homebrew installation.
• API keys (GROQ_API_KEY or OPENAI_API_KEY) are validated through _have_api_key() to enable Whisper transcription.
• Silent preflight mode (--check) returns exit code 0 for readiness or specific codes (2, 3, 4) for different failure states.
• Successful setup persists via _write_setup_complete(), making subsequent runs instantaneous.

Frequently Asked Questions

What file does the setup script check to determine if this is the first run?

The script looks for SETUP_COMPLETE=true inside ~/.config/watch/.env via the is_first_run() function in skills/watch/scripts/setup.py. If this marker is missing or not set to "true", the script executes the full installation flow.

Which external binaries are required for the /watch skill to function?

The setup script verifies the presence of ffmpeg, ffprobe, and yt-dlp on the system $PATH through _check_binaries(). On macOS, missing binaries are installed automatically via Homebrew; other platforms receive manual installation instructions.

What happens if I run the setup without a Whisper API key?

The skill can operate without transcription capabilities, falling back to frame-only analysis. However, cmd_install() will exit with code 3 and display a wizard prompt directing you to add either GROQ_API_KEY or OPENAI_API_KEY to ~/.config/watch/.env before marking setup as complete.

How does the silent preflight check work?

When invoked with --check, the script runs cmd_check() which aggregates system status through _status() and exits with code 0 if _status()["can_proceed"] is True. This silent validation allows the /watch skill to verify readiness without user interaction, returning non-zero exit codes for specific missing dependencies.

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