# How the setup.py Installer Detects Platform and Installs Dependencies in claude-video

> Discover how setup.py detects your platform macOS Linux or Windows and installs dependencies automatically using Homebrew or package manager commands.

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

---

**The [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) script uses Python's `platform.system()` function to identify macOS, Linux, or Windows, then executes platform-specific logic to either auto-install dependencies via Homebrew on macOS or provide package manager commands for Linux and Windows.**

The [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) installer serves as the pre-flight dependency manager for the **/watch** skill in the `bradautomates/claude-video` repository. Located at [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py), this script ensures that required binaries like `ffmpeg`, `ffprobe`, and `yt-dlp` are present before the video processing pipeline executes. Understanding how this installer detects your operating system and handles dependency resolution is essential for troubleshooting environment setup issues.

## Platform Detection with platform.system()

The installer begins by importing Python's built-in **platform** module to query the host operating system at runtime. According to the source code at line 23, the script imports `platform` to access the `system()` method.

When invoked without the `--check` or `--json` flags, the `cmd_install()` function captures the OS identifier and branches accordingly. As implemented in lines 3035-3042, the detection logic follows this pattern:

```python
system = platform.system()
if system == "Darwin":
    # macOS auto-install via Homebrew

elif system == "Linux":
    # print apt/pipx hints

elif system == "Windows":
    # print winget hints

else:
    # fallback message for unknown platforms

```

This branching structure ensures that each operating system receives appropriate installation instructions without unnecessary privilege escalation.

## Dependency Installation Logic

The installer employs different strategies depending on the detected platform. While **macOS** supports automatic installation through Homebrew, Linux and Windows receive detailed command hints because the repository avoids invoking `sudo` or privileged package managers directly.

### macOS Auto-Installation via Homebrew

On **Darwin** systems (macOS), the `_install_macos()` helper function checks for the presence of the Homebrew package manager. If `brew` is available, the script constructs a package list using the `_brew_pkg` variable and executes `brew install` commands automatically. This logic resides in lines 80-95 of [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py), enabling a zero-intervention setup experience for Mac users.

### Linux Installation Hints

For **Linux** environments, the `_install_hint_linux()` function assembles human-readable instructions targeting common package managers. As found in lines 196-202, the script provides specific commands for **APT** (Debian/Ubuntu) and **DNF** (Fedora/RHEL), plus a recommendation to use `pipx` for installing the `yt-dlp` Python tool. These hints guide users through manual installation without requiring the script to execute with elevated privileges.

### Windows Installation Hints

On **Windows**, the `_install_hint_windows()` function generates `winget` commands for acquiring `ffmpeg` and `yt-dlp`. Located at lines 207-213, this helper outputs copy-paste ready commands that leverage Windows Package Manager, allowing users to resolve dependencies through their preferred terminal without administrative complexity.

## Binary Checking and Execution Flow

The installation process begins with `_check_binaries()`, which verifies the presence of required executables in the system PATH. When a missing binary is detected, the script selects the appropriate platform-specific helper based on the earlier OS detection.

The `cmd_install()` function orchestrates this workflow: it identifies the operating system, invokes the relevant installation method, and exits with **status code 2** if dependencies remain unsatisfied after the hint or installation attempt. This explicit exit code allows automation scripts to detect incomplete setups programmatically.

## Running the Installer

Execute the script from the repository root to trigger platform detection and dependency resolution:

```bash

# Run the full interactive installer (detects platform automatically)

python3 skills/watch/scripts/setup.py

# Only perform a silent pre-flight check – returns 0 when ready

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

# Get a machine-readable JSON status report

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

```

Running [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) on macOS will attempt to install missing binaries via Homebrew automatically, while Linux or Windows executions output the appropriate installation hints for manual execution.

## Summary

- The installer uses **`platform.system()`** imported at line 23 to distinguish between Darwin, Linux, and Windows operating systems.
- **macOS** receives automatic dependency installation via the `_install_macos()` function and Homebrew (lines 80-95).
- **Linux** and **Windows** receive command hints through `_install_hint_linux()` (lines 196-202) and `_install_hint_windows()` (lines 207-213) rather than automatic installation.
- The `_check_binaries()` function validates requirements before the main logic branches, exiting with code **2** if dependencies are missing after attempted resolution.
- Three execution modes exist: interactive install, silent `--check`, and machine-readable `--json` output.

## Frequently Asked Questions

### How does setup.py detect the operating system?

The script calls **`platform.system()`** within the `cmd_install()` function to retrieve the OS name as a string ("Darwin", "Linux", or "Windows"). This value determines which platform-specific helper function executes, as shown in lines 3035-3042 of [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py).

### Does the installer automatically install dependencies on all platforms?

No. According to the `bradautomates/claude-video` source code, automatic installation only occurs on **macOS** when Homebrew is present. On Linux and Windows, the script prints specific installation hints using `apt`, `dnf`, `pipx`, or `winget` commands, requiring the user to execute them manually to avoid privilege escalation.

### What happens if a required binary is missing?

When `_check_binaries()` detects a missing dependency, the script invokes the appropriate platform handler. If automatic installation fails or the platform requires manual intervention (Linux/Windows), the installer prints the necessary commands and exits with **status code 2**, signaling that the environment is not ready for the /watch skill.

### Where can I find the platform-specific installation helpers?

The helper functions are defined in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py): **`_install_macos()`** at lines 80-95, **`_install_hint_linux()`** at lines 196-202, and **`_install_hint_windows()`** at lines 207-213. These functions handle the actual command generation and execution logic for their respective operating systems.