macOS Fresh Start Setup Guide

A comprehensive guide for setting up a fresh macOS installation with developer tools, productivity utilities, and system configurations. This guide assumes a clean macOS installation (Monterey 12.0 or later recommended).

System Preparation
Package Manager - Homebrew
Terminal Setup
Productivity Tools
Development Environment
System Utilities
Network & Security
Optional Configurations

System Preparation

1. System Updates

Before installing anything, ensure macOS is fully updated:

softwareupdate --list
softwareupdate --install --all

2. Command Line Tools

Install Xcode Command Line Tools (required for Homebrew and development):

xcode-select --install

Click “Install” when prompted. This installs essential tools like git, make, and compilers.

Verify Installation:

xcode-select -p
# Should output: /Library/Developer/CommandLineTools

3. System Preferences Setup

Before diving into software, configure key system settings:

Security & Privacy → FileVault: Enable disk encryption
Trackpad → Configure gestures and tracking speed
Keyboard → Set key repeat rate (System Preferences → Keyboard → Key Repeat: Fast, Delay Until Repeat: Short)
Dock → Configure position and auto-hide preferences
Finder → Preferences → Show all filename extensions

Package Manager - Homebrew

Homebrew is the essential package manager for macOS. It simplifies installing and managing software.

Installation

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Post-Installation Setup

Add Homebrew to your PATH (Apple Silicon Macs):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

For Intel Macs, Homebrew installs to /usr/local/bin and is automatically in PATH.

Verify Installation

brew doctor
brew --version

Update Homebrew

brew update
brew upgrade

Terminal Setup

A powerful terminal environment is essential for development work.

1. iTerm2

iTerm2 is a vastly improved terminal replacement for macOS.

Install:

brew install --cask iterm2

Launch iTerm2 from Applications or Spotlight.

Recommended Settings:

Preferences → Profiles → Colors → Color Presets → Import → Download Dracula theme
Preferences → Profiles → Text → Font → Select a Nerd Font (see below)
Preferences → Profiles → Keys → Load Preset → Natural Text Editing (enables Option + Arrow keys)

2. Oh My Zsh

Oh My Zsh is a framework for managing Zsh configuration with themes and plugins.

Install:

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

This will:

Install Oh My Zsh to ~/.oh-my-zsh
Create a backup of your existing .zshrc
Set Zsh as your default shell (if not already)

3. Powerlevel10k

Powerlevel10k is a fast, feature-rich Zsh theme with excellent customization.

Install:

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Configure .zshrc:

# Edit ~/.zshrc
nano ~/.zshrc

# Set the theme (find the ZSH_THEME line and change it):
ZSH_THEME="powerlevel10k/powerlevel10k"

Install Nerd Font (Required for icons):

brew tap homebrew/cask-fonts
brew install --cask font-meslo-lg-nerd-font

Configure iTerm2 to use the font:

iTerm2 → Preferences → Profiles → Text → Font
Select “MesloLGS NF” family
Size: 13-14pt recommended

Run Configuration Wizard:

source ~/.zshrc

Powerlevel10k will launch its configuration wizard. Follow the prompts to customize:

Prompt style (Lean, Classic, Rainbow, Pure)
Character set (Unicode)
Show/hide elements (git status, time, etc.)
Prompt connection (connected/disconnected)
Prompt heads (sharp, slanted, round)
Prompt tails
Prompt height (one line or two lines)
Prompt spacing
Icons (many, few, none)
Prompt flow (concise or fluent)
Enable transient prompt
Instant prompt mode (recommended: verbose)

Reconfigure anytime:

p10k configure

4. Useful Zsh Plugins

Edit ~/.zshrc and add these plugins to the plugins=() array:

plugins=(
  git
  docker
  terraform
  aws
  macos
  zsh-autosuggestions
  zsh-syntax-highlighting
)

Install additional plugins:

# zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions

# zsh-syntax-highlighting
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

Apply changes:

source ~/.zshrc

Productivity Tools

1. Alfred

Alfred is a powerful productivity application that replaces Spotlight with enhanced search, workflows, and automation.

Install:

brew install --cask alfred

Initial Setup:

Launch Alfred from Applications
Grant necessary permissions (System Preferences → Security & Privacy → Privacy)
Set hotkey (default: Cmd + Space, but you may want to remap Spotlight first)

Recommended Settings:

General → Set Alfred hotkey to Cmd + Space
Features → Enable clipboard history (free version)
Appearance → Choose a theme

Powerpack (Optional, Paid): The Powerpack unlocks workflows, clipboard history, snippets, and more. Consider purchasing from alfredapp.com.

Popular Free Workflows:

System commands (lock, sleep, restart)
Calculator with natural language
Dictionary lookups
File navigation

2. Rectangle

Rectangle is a window management app that lets you snap windows using keyboard shortcuts.

Install:

brew install --cask rectangle

Setup:

Launch Rectangle from Applications
Grant Accessibility permissions when prompted
Configure keyboard shortcuts (defaults are good)

Essential Shortcuts:

Ctrl + Opt + Left/Right - Snap window to left/right half
Ctrl + Opt + Up - Maximize window
Ctrl + Opt + Down - Restore window
Ctrl + Opt + C - Center window
Ctrl + Opt + Enter - Fullscreen

Alternative: Consider Magnet ($9.99, Mac App Store) or Moom for more features.

Development Environment

1. Docker Desktop

Docker provides containerization for development and testing environments.

Install:

brew install --cask docker

Initial Setup:

Launch Docker Desktop from Applications
Complete the Docker Desktop setup wizard
Agree to terms
Optionally create/sign in to Docker Hub account

Verify Installation:

docker --version
docker run hello-world

Recommended Settings:

Resources → Set memory/CPU limits based on your system
General → Enable “Start Docker Desktop when you log in” (optional)

Useful Docker Commands:

# List running containers
docker ps

# List all containers
docker ps -a

# Remove all stopped containers
docker container prune

# Remove unused images
docker image prune -a

2. AWS CLI

AWS Command Line Interface for interacting with AWS services.

Install:

brew install awscli

Verify Installation:

aws --version

Configure AWS CLI:

aws configure

You’ll be prompted for:

AWS Access Key ID
AWS Secret Access Key
Default region (e.g., us-east-1)
Default output format (json recommended)

Multiple Profiles:

# Configure additional profiles
aws configure --profile personal
aws configure --profile work

# Use specific profile
aws s3 ls --profile personal

Configuration Files:

Credentials: ~/.aws/credentials
Config: ~/.aws/config

3. Terraform

Infrastructure as Code tool for managing cloud resources.

Install:

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

Verify Installation:

terraform version

Enable Tab Completion:

terraform -install-autocomplete

Basic Usage:

# Initialize a working directory
terraform init

# Preview changes
terraform plan

# Apply changes
terraform apply

# Destroy infrastructure
terraform destroy

4. Claude CLI

Anthropic’s official CLI for Claude AI (formerly known as Claude Code).

Install:

brew install anthropic/claude/claude

Verify Installation:

claude --version

Initial Setup:

claude auth login

Follow the prompts to authenticate with your Anthropic account.

Basic Usage:

# Start an interactive session
claude

# Run a specific command
claude "How do I set up a cron job?"

# Use with files
claude "Review this code" < script.py

Configuration: Check configuration at ~/.config/claude/config.json

5. Cursor

AI-powered code editor built on VSCode (if “codex” refers to Cursor).

Install:

brew install --cask cursor

Alternative - Visual Studio Code: If you prefer VSCode:

brew install --cask visual-studio-code

First Launch:

Open Cursor from Applications
Sign in or create account for AI features
Install recommended extensions
Configure settings (sync, themes, keybindings)

Essential Extensions (if using Cursor/VSCode):

# Open Cursor and press Cmd+Shift+P → "Shell Command: Install 'cursor' in PATH"
# Then install extensions via command line:

cursor --install-extension ms-python.python
cursor --install-extension hashicorp.terraform
cursor --install-extension ms-azuretools.vscode-docker
cursor --install-extension eamodio.gitlens
cursor --install-extension esbenp.prettier-vscode

6. Git Configuration

Configure Git with your identity:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

# Set default branch name
git config --global init.defaultBranch main

# Enable credential helper
git config --global credential.helper osxkeychain

# Set default editor (nano, vim, or code/cursor)
git config --global core.editor nano

# Set pull behavior
git config --global pull.rebase false

# Enable color output
git config --global color.ui auto

View Configuration:

git config --global --list

SSH Key for GitHub/GitLab:

# Generate SSH key
ssh-keygen -t ed25519 -C "your.email@example.com"

# Start ssh-agent
eval "$(ssh-agent -s)"

# Add SSH key to agent
ssh-add ~/.ssh/id_ed25519

# Copy public key to clipboard
pbcopy < ~/.ssh/id_ed25519.pub

# Add to GitHub: Settings → SSH and GPG keys → New SSH key

7. Node.js and npm (Optional but Recommended)

Many development tools require Node.js.

Install via Homebrew:

brew install node

Verify:

node --version
npm --version

Alternative - Use nvm (Node Version Manager):

brew install nvm

# Add to ~/.zshrc:
export NVM_DIR="$HOME/.nvm"
[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"

# Install latest LTS
nvm install --lts
nvm use --lts

8. Python (Optional)

macOS includes Python 3, but you may want a managed version.

Install via Homebrew:

brew install python

Verify:

python3 --version
pip3 --version

Create Virtual Environments:

# Navigate to project directory
cd ~/projects/myproject

# Create virtual environment
python3 -m venv venv

# Activate
source venv/bin/activate

# Deactivate
deactivate

System Utilities

1. iStat Menus

Comprehensive system monitoring for macOS menu bar.

Install:

brew install --cask istat-menus

Setup:

Launch iStat Menus from Applications
Grant necessary permissions (Accessibility, Monitoring)
Configure which stats to display (CPU, Memory, Network, Disks, Battery, etc.)

Trial: iStat Menus offers a 14-day trial, then requires purchase (~$11.99).

Recommended Monitors:

CPU & GPU - Show percentage in menu bar
Memory - Show used/total
Network - Show upload/download speeds
Disks - Show available space
Battery (laptops) - Show percentage and time remaining

Alternative Free Options:

Activity Monitor (built-in)
MenuMeters (free, but less polished)
Stats (free, open source)

2. Fantastical

Premium calendar app with natural language parsing and excellent UX.

Install:

brew install --cask fantastical

Setup:

Launch Fantastical from Applications
Connect your calendar accounts (iCloud, Google, Exchange)
Configure appearance and notifications
Set as default calendar app

Key Features:

Natural language event creation (“Coffee with John tomorrow at 2pm”)
Unified calendar and task view
Time zone support
Meeting link integration (Zoom, Meet, Teams)

Pricing: Fantastical offers a free version with premium subscription for advanced features (~$4.99/month or $39.99/year).

Alternative Free Options:

Calendar (built-in macOS app)
Google Calendar (web/PWA)

Network & Security

1. AdGuard DNS

Configure system-wide ad blocking and privacy protection via DNS.

Public AdGuard DNS Servers:

Default (Ads & Trackers Blocking):

IPv4: 94.140.14.14 and 94.140.15.15
IPv6: 2a10:50c0::ad1:ff and 2a10:50c0::ad2:ff

Family Protection (Ads, Trackers, Adult Content):

IPv4: 94.140.14.15 and 94.140.15.16

Non-Filtering (No blocking, just fast DNS):

IPv4: 94.140.14.140 and 94.140.14.141

Configure on macOS:

Via System Preferences:
- Open System Preferences → Network
- Select your active connection (Wi-Fi or Ethernet)
- Click “Advanced”
- Go to “DNS” tab
- Click “+” to add DNS servers
- Add: 94.140.14.14 and 94.140.15.15
- Click “OK” → “Apply”
Via Command Line:

# List network services
networksetup -listallnetworkservices

# Set DNS for Wi-Fi
networksetup -setdnsservers Wi-Fi 94.140.14.14 94.140.15.15

# Set DNS for Ethernet
networksetup -setdnsservers Ethernet 94.140.14.14 94.140.15.15

# Verify DNS
networksetup -getdnsservers Wi-Fi

Flush DNS Cache:

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Test AdGuard DNS: Visit adguard.com/en/adguard-dns/check-dns.html to verify AdGuard DNS is active.

Alternative DNS Providers:

Cloudflare (Privacy-focused): 1.1.1.1 and 1.0.0.1
Cloudflare for Families (Malware blocking): 1.1.1.2 and 1.0.0.2
Google Public DNS: 8.8.8.8 and 8.8.4.4
Quad9 (Security-focused): 9.9.9.9 and 149.112.112.112

2. Little Snitch (Optional)

Advanced network monitoring and firewall for macOS.

Install:

brew install --cask little-snitch

Little Snitch monitors and controls outbound connections, showing which apps are connecting where. Premium software (~$45).

Optional Configurations

1. Dotfiles Management

Store your configuration files in a Git repository for easy backup and synchronization.

Common dotfiles:

.zshrc - Zsh configuration
.gitconfig - Git configuration
.aws/config - AWS profiles
.ssh/config - SSH configuration

Create dotfiles repository:

# Create directory
mkdir ~/dotfiles

# Move config files
mv ~/.zshrc ~/dotfiles/zshrc
mv ~/.gitconfig ~/dotfiles/gitconfig

# Create symlinks
ln -s ~/dotfiles/zshrc ~/.zshrc
ln -s ~/dotfiles/gitconfig ~/.gitconfig

# Initialize git repo
cd ~/dotfiles
git init
git add .
git commit -m "Initial dotfiles"

# Push to GitHub
git remote add origin git@github.com:yourusername/dotfiles.git
git push -u origin main

2. Homebrew Bundle

Create a Brewfile to track all installed applications for easy restoration.

Generate current Brewfile:

brew bundle dump --file=~/Brewfile

Contents will look like:

tap "hashicorp/tap"
tap "homebrew/cask-fonts"
brew "awscli"
brew "docker"
brew "terraform"
cask "alfred"
cask "iterm2"
cask "rectangle"

Restore from Brewfile:

brew bundle --file=~/Brewfile

3. macOS Defaults (Advanced)

Customize macOS behavior via command line (use with caution):

# Show hidden files in Finder
defaults write com.apple.finder AppleShowAllFiles -bool true

# Show path bar in Finder
defaults write com.apple.finder ShowPathbar -bool true

# Show status bar in Finder
defaults write com.apple.finder ShowStatusBar -bool true

# Disable "Are you sure you want to open this application?" dialog
defaults write com.apple.LaunchServices LSQuarantine -bool false

# Set fast key repeat rate
defaults write NSGlobalDomain KeyRepeat -int 1
defaults write NSGlobalDomain InitialKeyRepeat -int 10

# Disable auto-correct
defaults write NSGlobalDomain NSAutomaticSpellingCorrectionEnabled -bool false

# Show all file extensions
defaults write NSGlobalDomain AppleShowAllExtensions -bool true

# Restart Finder to apply changes
killall Finder

Backup before making changes:

# Export current defaults
defaults read > ~/macos-defaults-backup.txt

4. Additional Useful CLI Tools

# Modern replacements for standard tools
brew install bat          # Better 'cat' with syntax highlighting
brew install exa          # Better 'ls' with colors and icons
brew install ripgrep      # Better 'grep' (blazing fast search)
brew install fd           # Better 'find'
brew install htop         # Better 'top' (process viewer)
brew install tldr         # Simplified man pages
brew install jq           # JSON processor
brew install tree         # Directory tree viewer

# Add aliases to ~/.zshrc
echo "alias cat='bat'" >> ~/.zshrc
echo "alias ls='exa --icons'" >> ~/.zshrc
echo "alias ll='exa -la --icons'" >> ~/.zshrc
echo "alias grep='rg'" >> ~/.zshrc

source ~/.zshrc

5. Privacy & Security Hardening

# Enable Firewall
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on

# Enable Stealth Mode (don't respond to ping/ICMP)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setstealthmode on

# Disable Guest User
sudo dscl . -delete /Users/Guest

# Require password immediately after sleep/screensaver
defaults write com.apple.screensaver askForPassword -int 1
defaults write com.apple.screensaver askForPasswordDelay -int 0

# Disable crash reporter
defaults write com.apple.CrashReporter DialogType -string "none"

# Clear NVRAM (helps with tracking)
# Note: Only run if you know what you're doing
# sudo nvram -c

Post-Setup Checklist

System fully updated
FileVault encryption enabled
Homebrew installed and updated
iTerm2 configured with Powerlevel10k
Alfred/Rectangle installed and configured
Docker Desktop running
AWS CLI configured with credentials
Terraform installed
Claude CLI authenticated
Cursor/VSCode installed with extensions
Git configured with SSH keys
iStat Menus configured
Fantastical connected to calendars
AdGuard DNS configured
Dotfiles backed up to Git
Brewfile created for easy restoration

Quick Reinstall Script

Save this as ~/macos-setup.sh for future reinstalls:

#!/bin/bash

# macOS Fresh Setup Script
# Run with: bash ~/macos-setup.sh

set -e

echo "🚀 Starting macOS setup..."

# Install Homebrew
if ! command -v brew &> /dev/null; then
    echo "📦 Installing Homebrew..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    eval "$(/opt/homebrew/bin/brew shellenv)"
fi

# Install CLI tools
echo "🔧 Installing CLI tools..."
brew install awscli terraform git node python3

# Install applications
echo "📱 Installing applications..."
brew install --cask iterm2 alfred rectangle docker cursor istat-menus fantastical

# Install fonts
echo "🔤 Installing fonts..."
brew tap homebrew/cask-fonts
brew install --cask font-meslo-lg-nerd-font

# Install Oh My Zsh
if [ ! -d "$HOME/.oh-my-zsh" ]; then
    echo "💻 Installing Oh My Zsh..."
    sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" "" --unattended
fi

# Install Powerlevel10k
if [ ! -d "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k" ]; then
    echo "🎨 Installing Powerlevel10k..."
    git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k
    sed -i '' 's/ZSH_THEME=".*"/ZSH_THEME="powerlevel10k\/powerlevel10k"/' ~/.zshrc
fi

# Install Zsh plugins
echo "🔌 Installing Zsh plugins..."
git clone https://github.com/zsh-users/zsh-autosuggestions ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-autosuggestions
git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/plugins/zsh-syntax-highlighting

# Install Claude CLI
echo "🤖 Installing Claude CLI..."
brew install anthropic/claude/claude

echo "✅ Setup complete!"
echo ""
echo "Next steps:"
echo "1. Restart your terminal"
echo "2. Run 'p10k configure' to set up Powerlevel10k"
echo "3. Configure AWS CLI: aws configure"
echo "4. Authenticate Claude CLI: claude auth login"
echo "5. Set up AdGuard DNS in System Preferences → Network"
echo "6. Launch and configure: Alfred, Rectangle, iStat Menus, Fantastical"

Make it executable:

chmod +x ~/macos-setup.sh

Maintenance Commands

Weekly:

# Update all Homebrew packages
brew update && brew upgrade && brew cleanup

Monthly:

# Update macOS
softwareupdate --install --all

# Update Oh My Zsh
omz update

# Update npm packages (if using Node.js)
npm update -g

As Needed:

# Check for outdated Homebrew packages
brew outdated

# Remove old Homebrew downloads
brew cleanup -s

# Check Homebrew for issues
brew doctor

Troubleshooting

iTerm2 colors look wrong

Install a Nerd Font and set it in iTerm2 preferences
Import a color scheme (Dracula, Solarized, etc.)

Powerlevel10k icons not showing

Ensure you’ve installed a Nerd Font
Set the font in iTerm2: Preferences → Profiles → Text → Font

AWS CLI not found after installation

Ensure Homebrew is in your PATH
Restart your terminal
Try: brew doctor to check for issues

Docker Desktop won’t start

Check System Requirements (macOS 11+)
Ensure virtualization is enabled
Try removing and reinstalling: brew reinstall --cask docker

Permission issues with Homebrew

# Fix permissions
sudo chown -R $(whoami) $(brew --prefix)/*

Resources

Last Updated: 2025-11-12

macOS Fresh Start Setup Guide

On This Page

Table of Contents

System Preparation

1. System Updates

2. Command Line Tools

3. System Preferences Setup

Package Manager - Homebrew

Installation

Post-Installation Setup

Verify Installation

Update Homebrew

Terminal Setup

1. iTerm2

2. Oh My Zsh

3. Powerlevel10k

4. Useful Zsh Plugins

Productivity Tools

1. Alfred

2. Rectangle

Development Environment

1. Docker Desktop

2. AWS CLI

3. Terraform

4. Claude CLI

5. Cursor

6. Git Configuration

7. Node.js and npm (Optional but Recommended)

8. Python (Optional)

System Utilities

1. iStat Menus

2. Fantastical

Network & Security

1. AdGuard DNS

2. Little Snitch (Optional)

Optional Configurations

1. Dotfiles Management

2. Homebrew Bundle

3. macOS Defaults (Advanced)

4. Additional Useful CLI Tools

5. Privacy & Security Hardening

Post-Setup Checklist

Quick Reinstall Script

Maintenance Commands

Troubleshooting

iTerm2 colors look wrong

Powerlevel10k icons not showing

AWS CLI not found after installation

Docker Desktop won’t start

Permission issues with Homebrew

Resources