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, Railway CLI, Ollama for local models
• 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)

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, 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, [email protected]

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

# Media & processing
ffmpeg, yt-dlp, tesseract

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

# Databases
postgresql@14, rabbitmq

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

# 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

# Media
vlc, audacity, loom, descript

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

# Dev tools
beeper, superhuman

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

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

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)
• Screenflow 11 — screen recording
• 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