New Mac developer setup — the first hour after unboxing

A brand-new Mac can be ready for real development work in 30 to 60 minutes. This guide targets Apple Silicon + macOS 14 (Sonoma) or newer and gets you to the point of "open a terminal and git push" — no further.

Productivity tools (Raycast/Rectangle), editors, and language runtimes are covered by separate guides. Here we only install what's required to get to a working terminal.

TL;DR

1. Five macOS system settings (key repeat, trackpad, Finder, Dock, screenshots)
2. Xcode Command Line Tools → Homebrew → seven essential CLI tools (one brew line)
3. Git globals + SSH key (ed25519) → register on GitHub → gh auth login

Automation script (optional)

If you'd rather run a single script than follow each step — always download → verify SHA-256 → inspect → run.

# 1. Download
curl -fsSL https://devalice.jaceclub.com/assets/mac/initial-setup/setup-mac.sh -o setup-mac.sh
 
# 2. Verify SHA-256
shasum -a 256 setup-mac.sh
# expected: d6b501f8fa1986d980c70525d1d4476bef444bc0dd2c62fb13f2e5a9128c63cf
 
# 3. Inspect
less setup-mac.sh
 
# 4. Run
bash setup-mac.sh

The script is idempotent — safe to re-run after partial completion or failure. It automates the first six sections below; SSH key registration on GitHub and gh auth login still require manual confirmation in a browser.

If you'd rather understand each step, walk through the manual sections below.

Prerequisites

• macOS 14 (Sonoma) or newer — macOS 12 (Monterey) and earlier break with some recent Homebrew packages
• Apple Silicon (M1–M4) recommended — Intel Mac works, but the Homebrew prefix differs (/opt/homebrew vs /usr/local). Noted inline.
• Administrator account (sudo available)
• Internet connection and signed-in Apple ID

Intel Mac users: just remember that your Homebrew prefix is /usr/local. Otherwise this guide applies as-is.

1. macOS system settings — 5 minutes

Apply via System Settings or terminal commands. Do these once; the daily improvement is large.

1.1 Key repeat — the highest-leverage change

Defaults are far too slow and silently steal coding speed. Push them to the max.

# Key Repeat (rate after the first repeat) — faster than the slider's max
defaults write -g KeyRepeat -int 1
# Initial Key Repeat (delay before the first repeat) — shorter than the slider's min
defaults write -g InitialKeyRepeat -int 10

Log out and back in for this to take effect. (A reboot also works.)

1.2 Trackpad — tap-to-click + three-finger drag

# Enable tap-to-click
defaults write com.apple.AppleMultitouchTrackpad Clicking -bool true
defaults -currentHost write -g com.apple.mouse.tapBehavior -int 1

Three-finger drag is GUI-only: System Settings → Accessibility → Pointer Control → Trackpad Options → "Use trackpad for dragging" → "Three Finger Drag".

1.3 Finder — show hidden files, full paths, extensions

defaults write com.apple.finder AppleShowAllFiles -bool true
defaults write com.apple.finder _FXShowPosixPathInTitle -bool true
defaults write -g AppleShowAllExtensions -bool true
killall Finder

1.4 Dock — autohide, no animation

Reclaim screen real estate and speed up its appearance.

defaults write com.apple.dock autohide -bool true
defaults write com.apple.dock autohide-delay -float 0
defaults write com.apple.dock autohide-time-modifier -float 0.15
killall Dock

1.5 Screenshots — keep the desktop clean

The default location is the desktop, which clutters fast. Move them.

mkdir -p ~/Pictures/Screenshots
defaults write com.apple.screencapture location ~/Pictures/Screenshots
defaults write com.apple.screencapture type png
killall SystemUIServer

2. Xcode Command Line Tools — 5 minutes

Homebrew, Git, and compilers all depend on this.

xcode-select --install

A GUI dialog appears → Install → accept the license → wait ~5 minutes (~100 MB).

Verify

xcode-select -p
# /Library/Developer/CommandLineTools  ← expected

If you already have the full Xcode.app, you'll see /Applications/Xcode.app/Contents/Developer — also fine.

3. Homebrew + essential CLI — 10 minutes

3.1 Install Homebrew

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

When done, the installer prints PATH instructions. Apple Silicon — add these two lines to ~/.zprofile:

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

⚠️ Intel Mac: use /usr/local instead of /opt/homebrew. The installer's printed instructions are correct for your machine — follow them.

Verify

brew --version
# Homebrew 4.x.x
brew doctor
# Your system is ready to brew.

3.2 Seven essential CLIs in one line

The tools you'll use daily:

brew install git gh mise jq ripgrep fzf eza

fzf shell integration (optional)

Enable Ctrl+R history search:

$(brew --prefix)/opt/fzf/install --all

4. Git config + SSH key — 10 minutes

4.1 Git globals

Use the same email as your GitHub account.

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase false
git config --global core.editor "code --wait"  # if you'll use VS Code

code --wait requires VS Code to be installed. Skip for now if you don't have it yet.

4.2 SSH key — prefer ed25519

Shorter and safer than RSA 4096.

ssh-keygen -t ed25519 -C "you@example.com"
# Enter file in which to save: [Enter] (use default ~/.ssh/id_ed25519)
# Enter passphrase: [optional but recommended]

Register with ssh-agent and macOS Keychain:

eval "$(ssh-agent -s)"
 
cat <<'EOF' >> ~/.ssh/config
Host github.com
  AddKeysToAgent yes
  UseKeychain yes
  IdentityFile ~/.ssh/id_ed25519
EOF
 
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

4.3 Add the public key to GitHub + authenticate

Copy the public key to clipboard:

pbcopy < ~/.ssh/id_ed25519.pub

Open https://github.com/settings/ssh/new in a browser → Title: "Mac (model)" → Key: paste → Add SSH key.

Authenticate gh for HTTPS operations (PR creation, etc.):

gh auth login
# GitHub.com → HTTPS → Y (auth Git with GitHub credentials) → Login with a web browser

A browser will open with a one-time code. Enter it, then Authorize.

5. Verify — did everything install correctly?

One-shot check:

echo "--- Versions ---"
sw_vers | head -2
brew --version | head -1
git --version
gh --version | head -1
mise --version
echo "--- GitHub auth ---"
ssh -T git@github.com 2>&1 | head -1
gh auth status 2>&1 | head -3

Expected output:

--- Versions ---
ProductName: macOS
ProductVersion: 14.5
Homebrew 4.x.x
git version 2.46.x
gh version 2.x.x
mise 2026.x.x
--- GitHub auth ---
Hi <your-username>! You've successfully authenticated, but GitHub does not provide shell access.
github.com
  ✓ Logged in to github.com account <your-username>

If everything prints normally, you're done. You can now git clone <repo> and start work.

6. Troubleshooting

"command not found: brew" — PATH not loaded

Check that ~/.zprofile contains eval "$(/opt/homebrew/bin/brew shellenv)". Open a fresh terminal and try again.

"xcrun: error: invalid active developer path"

Command Line Tools are broken. Reinstall:

sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Homebrew install "Permission denied"

Permission issue on /opt/homebrew or /usr/local. Run the chown command the installer suggested verbatim.

SSH "Permission denied (publickey)"

ssh-add -l                              # is the key in the agent?
ssh -vT git@github.com 2>&1 | tail -20  # verbose output

If the key is missing, re-run ssh-add --apple-use-keychain ~/.ssh/id_ed25519. If it's still failing, verify the key is registered on GitHub.

git push keeps asking for a password

You cloned over HTTPS. Switch the remote to SSH:

git remote set-url origin git@github.com:<user>/<repo>.git

Some Homebrew packages fail on Apple Silicon

A few old packages run only under Rosetta 2:

softwareupdate --install-rosetta --agree-to-license
arch -x86_64 brew install <package>

What's next

This guide stopped at "terminal works for real". After this:

• Developer tooling: editors, runtimes (Node·Python·Ruby) — /mac/dev-toolchain
• Productivity tools: Raycast, Rectangle, Karabiner — /mac/productivity
• AI agent environment: Claude Code, Cursor — /ai-agents/claude-code
• Automation script is the section near the top of this page ✅

References

• Homebrew official
• GitHub SSH key registration
• mise official — runtime version manager
• gh CLI manual

Changelog

• 2026-05-12 — Initial translation (devAlice M2 i18n seed)