Interactive guide

Mac AI Dev Setup

Tick what your projects need. The page writes the commands in order, with a check after each one. Built from a real move to a new Apple Silicon Mac.

October 2026 / macOS, Apple Silicon

0 of 0 steps done

1 · Choose what you need

Start from

Always included: Xcode command line tools, Homebrew, git, GitHub CLI, jq, ripgrep, tree, and a GitHub login.

Not sure what you need?

Do the first steps and clone your repos, then run the scanner at the end of the plan. Paste its output here to tick the boxes for you.

Scanner output

2 · Run these in order

Use a normal Terminal window. Steps tagged Password ask for your Mac password. A coding agent can’t type it for you, and neither can the ! shortcut in Claude Code. Safe to re-run. Every step checks before it installs or writes, so a second run changes nothing. Files that other tools may have written are never overwritten. Honest labels. Run on M5 Pro means the commands were executed during the real migration. Tested in a scratch home means they ran against a throwaway home folder. Mirrors a working Mac means they copy a setup that already works. Standard command comes from the tool’s own docs and was not run here.

Field notes

Lessons from the move

Open a new terminal after installing Docker, Rust, Java or LaTeX. Their PATH changes only reach new shells.
macOS ships Python 3.9 for its own use. Install a current Python with Homebrew and give each project its own virtual environment, so nothing touches the system one.
npm 11 skips dependency install scripts. That is harmless for esbuild and fsevents, but puppeteer will not download its browser. Point it at Chrome instead.
BasicTeX is small on purpose. When a build says File 'x.sty' not found, run tlmgr search --global --file x.sty to find the package, then install it.
“Needs CUDA” usually means “written for NVIDIA”. Apple’s GPU (device mps) ran a 0.6B voice model faster than real time, while CPU mode did not finish. The code often hardcodes cuda and needs one line changed.
One failed download is not a failed script. A flaky DNS lookup for a package host looks like an error in your setup. Wait a minute and re-run.
oh-my-zsh’s installer renames your .zshrc. Pass KEEP_ZSHRC=yes, and write your config first so the file it keeps is the right one.
Guard every file write with [ -f file ] ||. A shared notes folder can gain files from another agent while you work, and a plain cat > will overwrite them.