Setting up a new Mac for Claude Code work, end-to-end

You just got a new Mac and your primary work will be Claude Code + surrounding tooling. This is the end-to-end setup — every step, every command, every config — to go from unboxed to your first productive Claude Code session in 90 minutes.

Pre-flight: things to do before opening the Mac

Two preparations:

1. Sign up for Anthropic API access

Visit console.anthropic.com. Create an account. Add payment method. Set a monthly budget limit (e.g., $200) to avoid surprises. Generate an API key. Save it to 1Password or your password manager.

2. Plan your Apple ID

If you have an existing Apple ID, sign in fresh. If you're using a new one, decide email + recovery method.

Time investment: 10 min before unboxing.

Phase 1 — macOS first-run (10 min)

Power on. Follow setup:

• Apple ID sign-in.
• Skip "Set Up Touch ID" if you want (do it later in System Settings).
• Skip "Migration Assistant" — fresh setup is cleaner. (See the new Mac setup post for migration vs fresh debate.)
• iCloud sign-in.
• Uncheck Desktop & Documents iCloud sync — interferes with developer workflows.

Done. You're at the desktop.

Configure Finder

• Finder → Settings → Advanced → Show all filename extensions.
• View → Show Path Bar.
• View → Show Status Bar.
• Sidebar → add Home folder.

Configure System

• System Settings → Accessibility → Display → Reduce Motion ON.
• System Settings → Keyboard → Key Repeat: Fast; Delay Until Repeat: Short.
• System Settings → Trackpad → Tap to click ON.

Phase 2 — Install Homebrew (5 min)

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

Follow post-install. Add to PATH:

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

Verify:

brew --version

Phase 3 — Core dev tools (15 min)

Install in this order:

# Terminal — install first since you'll use it for everything else
brew install --cask warp

# Editor
brew install --cask cursor    # AI-first; or visual-studio-code if free preference

# File manager
brew install --cask mq-dir

# Spotlight replacement
brew install --cask raycast

# Window tiling
brew install --cask rectangle

# Password manager
brew install --cask 1password

# Screenshot tool
brew install --cask cleanshot

Open each one as it installs. Sign in:

• Warp: optional account for cloud features (skip if you want).
• Cursor: account + Anthropic API key paste (Cursor uses Claude under the hood).
• mq-dir: just opens, no account.
• Raycast: free tier, no account needed initially.
• 1Password: sign in to your existing account, or create one.

Total time so far: ~30 min.

Phase 4 — CLI tools (10 min)

Switch to Warp. Install the CLI essentials:

brew install git gh                       # Git + GitHub CLI
brew install cmux                          # Terminal multiplexer for AI sessions
brew install yazi                          # Terminal file manager
brew install fd ripgrep bat eza fzf zoxide # Modern Unix tools
brew install jq                            # JSON tool, you'll thank yourself later

Configure git:

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 true
git config --global core.editor "cursor --wait"   # or "code --wait" / "vim"

Generate SSH key for GitHub:

ssh-keygen -t ed25519 -C "you@example.com"
# Press Enter for default location
# Set a passphrase (1Password can manage it)
gh auth login                              # follow prompts
gh ssh-key add ~/.ssh/id_ed25519.pub --title "$(scutil --get LocalHostName)"

Verify SSH:

ssh -T git@github.com
# Should output: Hi <your username>! You've successfully authenticated...

Phase 5 — Claude Code (10 min)

Install per Anthropic's current docs. As of 2026, typically:

# Per docs.claude.com/claude-code — verify the current install method
npm install -g @anthropic-ai/claude-code   # roughly; check official docs

Or via the official installer if Anthropic provides one.

Configure with your API key. Anthropic recommends setting it via env var, not in command line history:

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
source ~/.zshrc

(Better: store the key in 1Password and use 1Password CLI to inject it. See 1Password docs.)

Verify:

claude-code --version

Test in a temp directory:

mkdir /tmp/claude-test
cd /tmp/claude-test
claude-code
> Tell me what's in this directory.

If you get a sensible response, Claude Code is working.

Phase 6 — Dev directory layout (5 min)

mkdir -p ~/dev/{repos,sessions,_shared/{prompts,templates,references}}

Set up your workspace:

# Clone your dotfiles if you have them
git clone git@github.com:you/dotfiles ~/.dotfiles
cd ~/.dotfiles
./install.sh    # whatever your script is

# Or start fresh:
touch ~/.zshrc ~/.gitconfig

Open mq-dir. Configure 4-pane layout:

• Pane 1: ~/dev/sessions/
• Pane 2: ~/dev/repos/
• Pane 3: ~/dev/_shared/
• Pane 4: a project you'll start working on

Sidebar Favorites: drag the same 4 folders. Save as Project named "Daily."

Phase 7 — Global Claude Code config (10 min)

Create your global CLAUDE.md:

mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md <<'EOF'
# Global preferences

## Communication
- Prefer concise responses. Don't explain the obvious.
- When suggesting commands, give one option, not three.

## Code style
- Don't add error handling for cases that can't happen.
- Don't write comments explaining what code does.
- Comments only for non-obvious why.

## Reusable assets
- Prompt library: ~/dev/_shared/prompts/
- Templates: ~/dev/_shared/templates/
- References: ~/dev/_shared/references/

## When starting a new session
- Read ~/dev/sessions/<current>/CLAUDE.md if it exists.
- Read project-level CLAUDE.md if in a repo.
EOF

This is your global preferences file. Customize per your taste.

Phase 8 — First real session (10 min)

Spawn your first AI session:

# Pick a real project to start
cd ~/dev/repos
git clone git@github.com:you/somerepo
cd somerepo

# Use cmux to manage the session
cmux create explore-somerepo --dir $PWD
cmux attach explore-somerepo

# Inside cmux:
claude-code
> Explore this codebase. Surface the architecture in 5 bullet points.

If this works, you're set up.

In mq-dir, focus pane 4 on the repo directory. As Claude Code reads + writes files, you'll see them update in mq-dir's pane.

Phase 9 — Optional but recommended (15 min)

Things you can skip but probably won't want to:

Slack / Zoom (if you use them)

brew install --cask slack zoom

A note-taking app

brew install --cask obsidian   # markdown, file-based
# or
brew install --cask notion     # cloud-based

Spotify / Apple Music

brew install --cask spotify

Discord (if you're in OSS communities)

brew install --cask discord

Phase 10 — Save your config (5 min)

Capture what you installed for next-Mac reproducibility:

brew bundle dump --file=~/.dotfiles/Brewfile
cd ~/.dotfiles
git add Brewfile
git commit -m "brewfile snapshot — new mac setup"
git push

Now brew bundle install --file=Brewfile reproduces the install on your next Mac.

Total time investment

You're done. From unboxed Mac to working AI dev environment, including a real first Claude Code session, in under two hours.

What's next (over the first week)

Things that come naturally after the initial setup:

1. Build your prompt library — extract recurring prompts to ~/dev/_shared/prompts/. See the prompt library post.

2. Write project CLAUDE.md files — for each project, a focused CLAUDE.md. See the CLAUDE.md post.

3. Set up your fleet workflow — when you're running 3+ parallel sessions. See the parallel agent fleet post.

4. Configure Hammerspoon if you want automation — bind keyboard shortcuts to common actions.

5. Tune your editor — Cursor extensions, VS Code settings sync, dotfiles for keybinds.

Each is incremental; the core 90-min setup gets you productive.

Verdict

A new Mac dedicated to Claude Code work needs about 15 apps and 90 minutes to be fully productive. The list:

• Warp, Cursor (or VS Code), mq-dir, Raycast, Rectangle, 1Password, CleanShot
• git, gh, cmux, yazi, fd, ripgrep, bat, eza
• Claude Code itself

Total cost first year: ~$70 in app fees + variable Anthropic API ($50-150/mo depending on use).

This setup is reproducible — capture in a Brewfile + dotfiles + globalCLAUDE.md, deploy to next Mac in under 30 minutes.

mq-dir is the file manager designed for this exact workflow. Free, MIT, no telemetry. Pairs cleanly with Claude Code via the cmux sidebar integration.