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

> Learn how the Claude-Video setup and preflight check operate on the first run. This essential process ensures binaries, API keys, and configuration are ready before video processing begins.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: internals
- Published: 2026-07-19

---

**The `/watch` skill uses [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.

```bash

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

```bash

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

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/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.