New Mac Setup

New Mac Setup

This skill generates and runs a complete, idempotent Mac setup for fullstack web development and AI engineering. It produces 8 shell scripts that can be run individually or via a master runner, plus dotfiles and macOS preference automation.

The scripts are designed to be re-runnable — they check whether each tool is already installed before attempting installation, so you can safely run them again if something fails partway through.

Philosophy

The setup is opinionated. The core opinions:

• Terminal: Ghostty (fast, GPU-accelerated, Zig) + cmux (vertical tabs, split panes, socket API for AI agents). cmux reads Ghostty's config, so one config file serves both.
• Shell: ZSH with Oh-My-ZSH, powerlevel10k theme, zsh-autosuggestions, zsh-syntax-highlighting
• Node: fnm (not nvm — fnm is faster), pnpm and bun for package management/runtime
• Python: uv from Astral (not pyenv, not pip, not conda — uv is dramatically faster and handles both venvs and package installs)
• Docker: Colima (not Docker Desktop — lighter weight, CLI-native, free)
• Editor: Cursor (AI-native editor)
• AI tools: Claude Code, Codex CLI, Antigravity CLI (agy via the antigravity Homebrew cask), Railway CLI, Ollama for local models
• Transcription/diarization: ffmpeg + yt-dlp + MLX Whisper for fast local ASR, plus a Python 3.11 pyannote.audio environment for proper speaker diarization when HF_TOKEN is configured. Diarization should default to GPU/cloud paths; do not burn local CPU on long diarization unless explicitly requested.
• Agent notifications: peon-ping shared across Claude Code, Codex, and Cursor, tuned to notify only when useful
• Browser: Dia (from The Browser Company, successor to Arc)
• Launcher: Raycast (replaces Alfred, Spotlight, Caffeine, window management)
• Voice: Wispr Flow for voice-to-text
• Screenshots: Shottr (includes OCR) by default; also recommend Screendrop for local-first screenshot/screen recording, annotation, capture history, and optional Cloudflare-backed sharing.

How to Use This Skill

Step 1: Interview the User

Before generating scripts, ask the user a few questions to customize the setup. Key things to learn:

1. Git identity: name and email for git config
2. Hardware: Which Mac model / how much RAM? (affects which Ollama models to pull)
3. What to skip: Do they want everything, or should certain categories be excluded? (e.g., "no Elixir", "no PostgreSQL", "I use Docker Desktop not Colima")
4. Additions: Any apps or tools not in the default list?
5. Terminal preference: Ghostty + cmux is the default, but they may want something else

For RAM-based Ollama model recommendations:

• 8GB: qwen3.5:4b, qwen2.5-coder:3b
• 16GB: qwen3.5:9b, qwen2.5-coder:7b
• 24GB: qwen3.5:27b, qwen2.5-coder:14b (best sweet spot)
• 32GB+: qwen3.5:35b, qwen2.5-coder:32b

Step 2: Generate the Scripts

Generate 8 scripts into the user's chosen directory. Each script is standalone and idempotent. Use the templates in scripts/ as the base, customizing per the user's answers.

The scripts should run in this order:

01-xcode-and-homebrew.sh   # Xcode CLI tools + Homebrew (15-25 min)
02-shell-setup.sh          # Oh-My-ZSH + plugins + fonts
03-brew-packages.sh        # All brew formulae + cask apps
04-dev-environment.sh      # Node (fnm), Python (uv), Git, Docker
05-ai-tools.sh             # Claude Code, Codex CLI, Antigravity CLI, Ollama models, llama.cpp
06-dotfiles.sh             # .zshrc + Ghostty config
07-macos-settings.sh       # System preferences via defaults commands
00-run-all.sh              # Master runner (runs 01-07 in order)

Step 3: Execute

If possible, execute the scripts directly. If running in a VM/sandbox that can't reach the user's Mac, write the scripts to the workspace folder and put a one-liner in the clipboard:

cd /path/to/scripts && chmod +x ./*.sh && bash ./00-run-all.sh

Lessons Learned (Bugs to Avoid)

These are real issues encountered during testing. The scripts in scripts/ already incorporate these fixes, but if you're generating fresh scripts, keep these in mind:

1. fnm needs sourcing before npm works. After installing Node via fnm, the current shell doesn't have npm in PATH until you run eval "$(fnm env --use-on-cd)". Every script that uses npm/node must source fnm first.

2. Don't use set -e in the master runner. If one script fails (e.g., a brew cask 404s), set -e kills the entire pipeline. Individual scripts can use set -e if they handle errors gracefully, but the master runner should not.

3. Source brew and fnm in the master runner. Add these lines near the top of 00-run-all.sh so all child scripts inherit them:

   eval "$(/opt/homebrew/bin/brew shellenv)" 2>/dev/null || true
   eval "$(fnm env --use-on-cd)" 2>/dev/null || true

4. Smart quotes break shell commands. If writing commands to the clipboard, avoid curly/smart quotes. Use simple ASCII quotes only, or avoid quotes entirely where possible. The safest clipboard commands are single simple statements like bash ./07-macos-settings.sh.

5. Zoom and some casks require sudo. The Zoom installer triggers a Password: prompt. The user needs to be warned that some cask installs will pause for their password.

6. brew install yarn --ignore-dependencies is needed if Node is managed by fnm (not brew). Otherwise brew tries to install its own Node as a yarn dependency.

7. Ghostty config location: ~/.config/ghostty/config. cmux reads this same file.

Default Package Lists

Homebrew Formulae (CLI tools)

# Core dev tools
gh, git, fnm, pnpm, bun, z, diff-so-fancy

# Languages & runtimes
elixir, erlang, python@3.13

# Docker (no Docker Desktop)
colima, docker, docker-completion

# Media & processing
ffmpeg, yt-dlp, tesseract, libsndfile

# Build dependencies
openssl@3, readline, sqlite, xz, zstd

# Databases
postgresql@14, rabbitmq

# Misc CLI
honcho, pipx, flyctl, entr, tig, mas, terminal-notifier, googleworkspace-cli

# Google Workspace
googleworkspace-cli installs the `gws` binary; auth still requires `gws auth setup` and `gws auth login`.

# Libraries
cairo, glib, harfbuzz, libvmaf, webp

Homebrew Casks (GUI apps)

# Terminal
ghostty

# Editors
cursor, visual-studio-code

# Browser
thebrowsercompany-dia

# Communication
slack, discord, zoom

# Productivity
raycast, rectangle, obsidian, notion, notion-calendar

# AI & ML
ollama, antigravity

# Media
vlc, audacity, tella, descript

# Utilities
shottr, notunes, caffeine, stretchly, quickshade, pure-paste, 1password

# Dev tools
beeper, superhuman, gcloud-cli

Plus cmux via: brew tap manaflow-ai/cmux && brew install --cask cmux

gcloud-cli installs Google Cloud CLI (gcloud). Keep /opt/homebrew/share/google-cloud-sdk/bin on PATH so additional SDK components are available after install.

Claude-Suggested Additions (March 2026)

These tools were suggested by Claude during the initial setup session and accepted by the user. They are now part of the default install in 03-brew-packages.sh:

1. fzf — Fuzzy finder that transforms shell history (Ctrl+R), file search, and git branch selection. Pairs perfectly with zsh-autosuggestions. brew install fzf
2. ripgrep (rg) — Blazingly fast grep replacement. Respects .gitignore, searches recursively by default. Essential for any developer. brew install ripgrep
3. bat — cat with syntax highlighting, line numbers, and git integration. Makes reading code files in terminal beautiful. brew install bat
4. zoxide — Drop-in z replacement with a smarter frecency algorithm and fuzzy matching. Same muscle memory, better results. brew install zoxide
5. Orbstack — Even lighter than Colima for Docker containers and Linux VMs. Has a nice GUI and near-instant startup. brew install --cask orbstack

Global npm Packages

undollar, npm-check-updates, trash-cli,
@anthropic-ai/claude-code, @openai/codex, @railway/cli

Antigravity CLI

Install Google Antigravity through Homebrew:

brew install --cask antigravity

The cask installs the desktop app and exposes agy as the Antigravity CLI. Prefer this over Gemini CLI for new setups: Google announced on May 19, 2026 that consumer Gemini CLI access for free, Google AI Pro, and Ultra users stops serving requests on June 18, 2026. Enterprise and paid API-key Gemini CLI access can remain available, but this new-Mac path should default to Antigravity CLI.