Reproducible macOS setup

A developer Mac that stays understandable.

effective-mac-setup is an opinionated, forkable baseline for people who want a fast developer machine without turning their home directory into a mystery box.

View on GitHub Read the quick start

Why it exists

Fresh Macs are pleasant. Rebuilding them by hand is not.

This setup keeps the important choices in version control: which tools are installed, which shell and editor settings are managed, which defaults are intentional, and which checks prove the machine is healthy.

It is small on purpose. The point is not to capture every preference a Mac has ever written. The point is to make the useful parts reviewable, repeatable, and easy to adapt.

What it manages

The setup owns the pieces that benefit from being explicit.

Packages and apps

A curated Brewfile installs command-line tools, desktop apps, and Mac App Store entries with comments explaining the choice.

Dotfiles

Git, zsh, fish, Starship, Zed, Ghostty, Colima, and shared helper commands are managed through chezmoi.

macOS defaults

System settings live in a small reviewed script, documented next to the command that applies each behavior.

Bootstrap and doctor

The bootstrap gets a new machine started. The doctor checks packages, runtimes, auth, dotfiles, and shell setup afterward.

What it avoids

Not everything belongs in Git.

  • No secrets or plaintext API tokens.
  • No blind dumps of macOS preference files.
  • No attempt to back up the whole machine.
  • No surprise changes to account login shell or private state.

Principles

Readable choices beat clever automation.

Prefer boring files over hidden loaders.

Track decisions close to the config they affect.

Make destructive or surprising commands explicit.

Treat macOS defaults as reviewed code.

Tooling overview

A compact baseline for modern application work.

Development

Git, Git LFS, GitHub CLI, GitHub Desktop, Zed, Go, Rust, Codex.

Shell and CLI

fish, Starship, zoxide, ripgrep, fd, jq, bat, eza, Semgrep.

Runtime and containers

fnm, Corepack, pnpm, Docker CLI, and Colima as the local runtime.

Browsers and testing

Firefox, Chrome, Helium, Polypane, and Velja for link routing.

AI and agents

Codex, Claude, Ollama, cmux, and a terminal setup that keeps them usable.

Daily Mac work

1Password, Backblaze, Tailscale, writing tools, media utilities, and office apps.

Start here

Fork it, review it, then let the scripts do the boring parts.

  1. 1

    Install Xcode Command Line Tools and Homebrew.

  2. 2

    Clone your fork and run scripts/bootstrap.sh.

  3. 3

    Review macos/defaults.sh, apply it when it fits, then run scripts/doctor.sh.

Open the full quick start in the README