---

name: new-mac-setup description: | Fully automated new Mac setup for fullstack web developers and AI engineers. Generates and executes idempotent shell scripts to install dev tools, CLI utilities, GUI apps, AI/ML tooling, shell config, and macOS preferences — all via Homebrew, fnm, uv, and defaults commands. Use this skill whenever someone says "set up my Mac", "new Mac setup", "configure my dev machine", "install my dev tools", "fresh Mac install", "developer environment setup", or anything about bootstrapping a macOS machine for development. Also trigger when someone mentions setting up Homebrew, Oh-My-ZSH, Node.js, Python, Docker, or terminal configuration on a new Mac — even if they don't call it a "setup". This skill is opinionated and based on real-world experience setting up M-series Macs for fullstack JS/TS + Python + AI development. license: MIT compatibility: | Requires macOS on Apple Silicon (M1/M2/M3/M4). Scripts use Homebrew, which handles all dependencies. Bash 3.2+ (ships with macOS). Internet connection required for package downloads. metadata: author: swyxio version: "2.0" last-updated: "2026-06-13" hardware: Apple Silicon (M-series) primary-stack: TypeScript, Python, AI/ML

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.

Transcription And Diarization Defaults

Install the local transcription stack on new AI/dev Macs because it is useful for meetings, podcasts, YouTube/video workflows, and searchable archives.

Add this to 03-brew-packages.sh / 04-dev-environment.sh generation:

brew install ffmpeg yt-dlp libsndfile
uv tool install mlx-whisper || true

mkdir -p "$HOME/.local/share/transcribe-anything"
uv venv --python 3.11 "$HOME/.local/share/transcribe-anything/.venv-pyannote"
uv pip install --python "$HOME/.local/share/transcribe-anything/.venv-pyannote/bin/python" \
  "pyannote.audio" soundfile

Guidance for generated docs:

• mlx_whisper is the preferred local ASR path on Apple Silicon when available.
• pyannote.audio direct is the preferred diarization path when HF_TOKEN is configured and the user has accepted Hugging Face model terms, but run it on CUDA/cloud GPU for long files.
• Users must accept terms for pyannote/speaker-diarization-community-1 and pyannote/segmentation-3.0, then set HF_TOKEN in their shell or secret manager. Never bake tokens into generated setup scripts.
• CPU pyannote on macOS is opt-in only for short tests. For real meeting/podcast diarization, use CUDA/cloud GPU or a managed diarization API such as Deepgram/AssemblyAI.
• Do not rely on simple Resemblyzer/librosa clustering of Whisper segments for production diarization; it commonly collapses multi-speaker meetings into one speaker.

peon-ping Defaults

When setting up AI tools on a new Mac, also install and configure peon-ping with these defaults:

• Install globally with the shared runtime under ~/.claude/hooks/peon-ping/ so Claude Code, Codex, and Cursor can all use the same install.
• Register Claude Code hooks normally via the installer.
• Register Codex manually in ~/.codex/config.toml:

  notify = ["bash", "/Users/$USER/.claude/hooks/peon-ping/adapters/codex.sh"]
  

• Keep Cursor hooked up if ~/.cursor/ exists.
• Use default_pack: "peon" as the fallback pack.
• Install this rotation pool: glados, jarvis, r2d2, peasant, sc_kerrigan, sc_scv, sc_marine, sc_raynor, sc_ghost, sc_terran, protoss, sc2_alarak, sc2_abathur, ra2_eva_commander, ra2_kirov, ra2_yuri, ra_soviet, ccg_gla_worker, ccg_us_dozer, ccg_china_dozer
• Set pack_rotation_mode to round-robin.
• Set volume to 0.2.
• Keep desktop_notifications enabled, but use notification_style: "standard" rather than large overlays.
• Install terminal-notifier via Homebrew so standard macOS notifications work reliably and support click-to-focus behavior.
• Set suppress_sound_when_tab_focused: true.
• Set silent_window_seconds: 30 so task.complete only fires for longer-running work.
• Categories:
  • session.start: false
  • task.acknowledge: false
  • task.complete: true
  • task.error: true
  • input.required: true
  • resource.limit: true
  • user.spam: false
• Goal: alerts only for meaningful attention events, with completion sounds reserved for work that took long enough to matter.

Ollama Models (for 24GB RAM)

qwen3.5:27b                    # General purpose (256K context, multimodal)
qwen2.5-coder:14b              # Code-focused
deepseek-r1:8b                 # Reasoning

macOS Defaults (automated)

# Finder: show extensions, show dotfiles, show path bar, list view
# Dock: auto-hide, no recents, no delay, minimize to app icon
# Keyboard: no autocorrect, no smart quotes, fast repeat, no press-and-hold
# Trackpad: no natural scrolling, tap to click
# Screenshots: PNG, Desktop, no shadow
# Menu bar: auto-hide

macOS Settings (manual — guide the user)

These can't be automated via defaults write:

1. Spotlight: disable all except Apps + System Settings
2. Siri: disable
3. Screenshot shortcut: remap to Cmd+E
4. Cmd+Q: remap to double-tap (prevent accidental quits)
5. Trackpad: disable dictionary lookup
6. Finder: set new windows to ~/Work
7. Dock: remove all icons except Finder and Trash
8. Cursor size: set to large in Accessibility (good for presentations)

Apps to Download Manually

These aren't in Homebrew or need manual install:

• Wispr Flow — voice-to-text (2025 pick)
• SuperWhisper — voice-to-text (2024 pick, still good)
• Screendrop — local-first screenshots, screen recordings, annotation, capture history, and optional Cloudflare-backed sharing; recommended alongside Shottr
• Screenflow 11 — screen recording
• Tella.tv — screen recording; preferred replacement for Loom
• App Quitter — close apps when windows close
• Clipbook or Alfred — clipboard manager

Post-Install: Open Apps That Need Login

After all scripts finish, open these apps to sign in and configure them. The skill should auto-open them for the user:

# Apps that need login/activation after install
open -a "Slack"
open -a "Discord"
open -a "Raycast"
open -a "Shottr"
open -a "1Password"
open -a "Spotify"
open -a "Zoom"
open -a "Dia"
open -a "GitHub Desktop" 2>/dev/null
open -a "Claude" 2>/dev/null
echo "🔑 Sign into each app above, then continue setup."

Browser Extensions (install in Dia/Chrome)

Essential:

• uBlock Origin, Privacy Badger, Video Speed Controller (highly recommended)
• Refined GitHub, React Developer Tools, Code Copy
• 1Password / LastPass

Nice to have:

• Morpheon Dark, bypass-paywalls-chrome, Twitter-Links-beta
• enhanced-history, Display Anchors, Octolinker, little-rat, RescueTime

Suggested Additions

Things worth considering that aren't in the original blog posts but complement this setup well:

1. mise (mise.jdx.dev) — universal version manager for Node, Python, Ruby, Go, etc. Could replace fnm + uv for version management (swyx mentioned exploring this)
2. zoxide — smarter z alternative with fuzzy matching
3. bat — cat replacement with syntax highlighting
4. eza — modern ls replacement
5. fd — faster find alternative
6. ripgrep — faster grep (rg)
7. fzf — fuzzy finder for shell history, files, everything
8. starship — cross-shell prompt (alternative to powerlevel10k, works with fish too)
9. Bartender or Ice — menu bar icon management (declutter)
10. Hand Mirror — quick webcam check from menu bar (great before calls)
11. Tailscale — mesh VPN for accessing home machines
12. Orbstack — another Docker Desktop alternative (even lighter than Colima)
13. Aerospace — tiling window manager (if Rectangle isn't enough)

Dotfiles Reference

The .zshrc should include:

• Oh-My-ZSH with powerlevel10k theme
• Plugins: git, zsh-autosuggestions, zsh-syntax-highlighting, z
• Homebrew, fnm, and uv PATH setup
• z directory jumping source
• Git aliases (gs, gd, gc, gp, gl, gco, gcb)
• npm/pnpm aliases (ni, nr, pi, pr, ncu)
• Python aliases (pip → uv pip, venv → uv venv)
• Docker aliases (dstart → colima start, dstop → colima stop)
• Editor set to Cursor

The Ghostty config should include:

• Font: "Meslo LG M for Powerline" at 14pt
• Theme: dark:GruvboxDark,light:GruvboxLight
• Shell integration: zsh
• Block cursor, no blink
• Global hotkey: Cmd+` for quick terminal
• Clipboard read/write enabled
• Mouse hide while typing