New Mac Setup#

Use this workflow to configure a new Mac from scratch with the tools and shell environment needed for development and daily work.

Trigger#

Use this when setting up a new Mac or rebuilding a machine after a wipe.

Inputs#

Before starting, have:

• A Mac with macOS up to date
• An Apple ID signed in
• Internet access
• Your Microsoft 365 licence or account credentials
• Your GitHub username and email address

1. Install Homebrew#

Homebrew is the package manager for everything else. Install it first.

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

After the installer finishes, follow the printed instructions to add Homebrew to your PATH. On Apple Silicon this is usually:

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

Verify:

brew --version

2. Install Warp#

Warp is the terminal. Install it via Homebrew:

brew install --cask warp

Open Warp from /Applications and complete the initial setup. From this point forward, use Warp as your terminal.

3. Configure Zsh and Oh My Zsh#

macOS ships with Zsh as the default shell. Oh My Zsh adds themes, plugins, and helpers on top of it.

Install Oh My Zsh:

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

After installation, your shell config lives at ~/.zshrc. Open it to make changes:

open ~/.zshrc

A minimal starting config:

export ZSH="$HOME/.oh-my-zsh"
ZSH_THEME="robbyrussell"
plugins=(git z macos)
source $ZSH/oh-my-zsh.sh

Reload the config:

source ~/.zshrc

4. Install pyenv and Python#

pyenv manages multiple Python versions without touching the system Python.

Install pyenv:

brew install pyenv

Add pyenv to your shell. Append these lines to ~/.zshrc:

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"

Reload:

source ~/.zshrc

Install the latest stable Python and set it as the global default:

pyenv install --list | grep "  3\." | tail -5   # see recent 3.x versions
pyenv install 3.13.3                             # replace with the version you want
pyenv global 3.13.3

Verify:

python --version
pip --version

5. Install VS Code#

Install Visual Studio Code via Homebrew:

brew install --cask visual-studio-code

Open VS Code and install the Shell Command so you can launch it from the terminal:

1. Open the Command Palette: Cmd+Shift+P
2. Type shell command and select Install ‘code’ command in PATH

Verify:

code --version

6. Install Rectangle#

Rectangle handles window management with keyboard shortcuts and snap areas. Drag a window to a screen edge to snap it to half, quarter, or full screen, or use keyboard shortcuts for the same actions.

Install via Homebrew:

brew install --cask rectangle

Alternatively, download the DMG directly from rectangleapp.com.

Open Rectangle from /Applications. Grant the Accessibility permission when prompted (System Settings → Privacy & Security → Accessibility).

Useful defaults to configure in Rectangle → Settings:

• Snap windows by dragging to screen edges — enabled by default
• Adjust or disable individual shortcuts to avoid conflicts with other apps
• Use Import to load a previously exported RectangleConfig.json for instant cross-machine parity

7. Install Finicky#

Finicky routes browser links to the right browser based on rules. Useful when you use different browsers for work and personal tasks.

brew install --cask finicky

Open Finicky and set it as the default browser when macOS prompts you.

Create a config file at ~/.finicky.js:

module.exports = {
  defaultBrowser: "Safari",
  rules: [
    {
      match: ["*.google.com/*", "*.github.com/*"],
      browser: "Google Chrome",
    },
  ],
};

Adjust defaultBrowser and rules to match your workflow. Finicky reloads the config automatically when the file is saved.

8. Install Microsoft Office#

Install Microsoft Office (Word, Excel, PowerPoint, Outlook, Teams) via Homebrew:

brew install --cask microsoft-office

After installation, open any Office app and sign in with your Microsoft 365 account to activate.

9. Final checks#

Verify each tool is available:

brew --version
warp --version || echo "Check /Applications/Warp.app"
echo $ZSH   # should print ~/.oh-my-zsh
python --version
pyenv version
code --version

Check the macOS login items or System Settings to confirm that Rectangle and Finicky are set to launch at login.

Decision points#

Review#

Before calling the setup complete, confirm:

• brew --version returns a version number
• Warp opens and the prompt shows correctly
• echo $ZSH prints the Oh My Zsh path
• python --version returns the version you installed via pyenv
• code --version returns a version number
• Rectangle responds to at least one window-snap shortcut
• Finicky is set as the default browser in System Settings → Desktop & Dock → Default web browser
• Microsoft Office opens and shows an active licence

Troubleshooting#

Output#

At the end, you should have:

• Homebrew installed and working
• Warp as the primary terminal
• Zsh configured with Oh My Zsh
• pyenv managing Python
• VS Code with the code CLI available
• Rectangle managing windows
• Finicky routing links to the right browser
• Microsoft Office activated

Notes#

Save these after setup:

• macOS version:
• Date set up:
• Python version installed:
• Oh My Zsh theme chosen:
• Finicky default browser: