# Setup

> Sets up a Mac for ButterCut. Installs all required dependencies (Homebrew, Ruby, Python, FFmpeg, WhisperX). Use when user says "install buttercut", "set up my mac", "get started", "first time setup", "install dependencies" or "check my installation".

- Skill: `barefootford/setup` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add barefootford/setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/barefootford/setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: barefootford (https://skillmd.com/u/barefootford)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/barefootford/setup

---


# Skill: Mac Setup

Sets up a Mac for ButterCut. Two installation paths available based on user preference.

## Step 1: Check Current State

Run each check below. Each command exits 0 when the dependency is present. Note which ones fail — that's what setup needs to install.

- [ ] **Xcode CLI Tools** — `xcode-select -p` (fix: `xcode-select --install`)
- [ ] **Homebrew** — `which brew` (fix: see https://brew.sh)
- [ ] **Ruby 3.3.x** — `ruby --version | grep -q 'ruby 3\.3'` (fix: install Ruby 3.3.6, see `.ruby-version`)
- [ ] **Bundler** — `which bundle` (fix: `gem install bundler`)
- [ ] **Python 3.12.x** — `python3 --version | grep -q 'Python 3\.12'` (fix: install Python 3.12.8, see `.python-version`)
- [ ] **FFmpeg** — `which ffmpeg` (fix: see FFmpeg install in the setup file below — must be the `homebrew-ffmpeg/ffmpeg` tap build)
- [ ] **FFmpeg drawtext filter** — `ffmpeg -hide_banner -filters 2>/dev/null | grep -q ' drawtext '` (fix: the stock `brew install ffmpeg` formula often omits drawtext; replace it with the `homebrew-ffmpeg/ffmpeg` tap build — see setup file)
- [ ] **WhisperX** — `which whisperx || test -x ~/.buttercut/whisperx || test -x ~/.buttercut/venv/bin/whisperx` (fix: see setup steps below)
- [ ] **Gems installed** — `bundle check` (fix: `bundle install` in buttercut directory)

If everything passes, tell the user they're ready to go and stop.

## Step 2: Ask User Preference

If dependencies are missing, use AskUserQuestion:

```
Question: "How would you like to install ButterCut?"
Header: "Install type"
Options:
  1. "Simple (recommended)" - "Fully automatic setup. We'll install everything for you using sensible defaults."
  2. "Advanced" - "For developers who want control. You manage Ruby/Python versions with your preferred tools."
```

## Step 3: Run Appropriate Setup

Based on user choice:

- **Simple**: Read and follow `skills/setup/simple-setup.md`
- **Advanced**: Read and follow `skills/setup/advanced-setup.md`

## Step 4: Verify Installation

After setup completes, re-run the checklist from Step 1 and report results to the user.

## Step 5: Ask About Error Reports

Only if `ruby lib/buttercut/report.rb consent` prints `error_reporting=unset` — otherwise this user has already answered, so leave it alone.

Ask the two questions in `skills/report-bug/SKILL.md` (step 2), worded for a fresh install rather than a crash: "ButterCut sometimes hits errors. Want me to send those to the team so they can fix them?" Save the answers by setting `error_reporting:` and `error_report_email:` in `libraries/settings.yaml`.

Keep it to those two questions and move on — it's the last thing standing between them and their first cut.