Setup Preflight Process and First-Run Detection in Claude-Video

Claude-Video's watch skill uses a Python pre-flight script (setup.py) that checks for required binaries and API keys, exits silently on success, and guides users through first-run installation when the SETUP_COMPLETE flag is missing from ~/.config/watch/.env.

The bradautomates/claude-video repository ships a dedicated watch skill that requires specific external dependencies and API credentials before it can process video content. Understanding the setup preflight process ensures you can diagnose configuration issues quickly and confirm that your environment is ready for the /watch command.

How First-Run Detection Works

The is_first_run() function in skills/watch/scripts/setup.py determines whether the setup wizard needs to execute by checking the user configuration file at ~/.config/watch/.env.

Specifically, the function inspects the SETUP_COMPLETE environment variable (lines 124-127). If this variable is unset or not equal to "true", the function returns True, signaling that the user has not yet completed the initial installation workflow.

This flag serves as a persistent marker across sessions. Once the installation flow successfully detects a valid Whisper API key and writes SETUP_COMPLETE=true to the .env file, subsequent runs skip the interactive setup prompts.

Pre-flight Verification Logic

Before the /watch command can execute, the cmd_check() function (invoked with the --check flag) performs a comprehensive environment verification via the internal _status() helper (lines 59-71).

Binary Availability Checks

The _check_binaries() function verifies that ffmpeg, ffprobe, and yt-dlp are present on the system PATH. Any missing binaries are recorded in the status dictionary for later reporting.

API Key Validation

The _have_api_key() function searches for transcription credentials by first checking environment variables, then falling back to the .env file via _read_env_key(). Claude-Video supports both Groq and OpenAI API keys for Whisper transcription services.

Status State Machine

The _status() function (lines 17-28) aggregates these checks into a structured dictionary containing four possible states in the status field:

• ready – All dependencies present and API key configured
• needs_install – Missing required binaries
• needs_key – First run without API key
• needs_install_and_key – Both binaries and API key missing

Installation and Setup Workflow

When executed without flags, cmd_install() (lines 99-115) enters the default installation mode. This workflow handles platform-specific dependency management and environment scaffolding.

On macOS, the script attempts to auto-install missing binaries using the appropriate package manager. On Linux and Windows, it prints platform-specific installation hints rather than attempting automated installation.

The function also ensures the configuration directory exists at ~/.config/watch/ and scaffolds a placeholder .env file if one does not already exist. This prevents the loss of user-configured settings like watch_detail between runs.

Completing First-Run Setup

The installation process marks setup completion only when _have_api_key() detects a valid Whisper API key. At that point, the script writes SETUP_COMPLETE=true to the .env file (lines 34-41), ensuring is_first_run() will return False on subsequent executions.

Silent Check Mode and Exit Codes

The pre-flight system supports a silent operation mode designed for integration with the main /watch entry point. When called with --check, the script exits with status 0 and produces no output if the environment is ready (can_proceed is True).

If checks fail, the script prints a single actionable error line to stderr and returns a specific exit code:

• Exit code 2 – Required binaries are missing
• Exit code 3 – First run detected without an API key
• Exit code 4 – Both binaries missing and no API key configured

This design allows the parent process to distinguish between recoverable configuration errors and runtime failures without parsing verbose log output.

Running the Setup Script

You can invoke the pre-flight checks manually to verify your environment or trigger the installation wizard.

Run a silent pre-flight check (used internally by /watch):

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

Print a machine-readable status snapshot:

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

Perform a full installation (first run):

python3 skills/watch/scripts/setup.py

The full installation installs missing binaries on macOS, prints hints for other platforms, scaffolds ~/.config/watch/.env, and writes SETUP_COMPLETE=true once a valid API key is detected.

Summary

• The is_first_run() function in skills/watch/scripts/setup.py checks the SETUP_COMPLETE flag in ~/.config/watch/.env to determine if initial setup is required.
• Pre-flight verification validates the presence of ffmpeg, ffprobe, and yt-dlp binaries plus a Whisper API key (Groq or OpenAI).
• The _status() function encodes environment readiness into four states: ready, needs_install, needs_key, or needs_install_and_key.
• Silent mode (--check) returns exit code 0 on success, or codes 2, 3, or 4 to indicate specific missing dependencies.
• The installation workflow is idempotent, preserving existing API keys and only writing the completion flag when credentials are confirmed.

Frequently Asked Questions

How does Claude-Video detect if it has been run before?

Claude-Video detects first-run status by reading the SETUP_COMPLETE environment variable from the .env file located at ~/.config/watch/. If this variable is missing or not set to "true", the is_first_run() function returns True, triggering the installation wizard.

What external dependencies are required for the watch skill?

The watch skill requires three external binaries: ffmpeg, ffprobe, and yt-dlp. These must be available on the system PATH before the /watch command can process video content. Additionally, you must configure either a GROQ_API_KEY or OPENAI_API_KEY for Whisper transcription services.

Can I run the setup script multiple times safely?

Yes, the setup process is idempotent. Re-running setup.py will not overwrite existing API keys in your .env file, and the script only marks setup as complete when it detects a valid Whisper key. You can safely run the script to verify binary availability or update your configuration.

What do the different exit codes mean when using --check?

Exit code 0 indicates the environment is ready for the /watch command. Exit code 2 means required binaries are missing, code 3 indicates a first-run scenario without an API key, and code 4 signals that both binaries and an API key are needed. These codes allow automated tools to handle specific configuration errors programmatically.

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