Install

Homebrew

Install from brew.sh. It asks for your Mac password (typing shows nothing), and on a fresh Mac it installs Apple's Command Line Tools too, which is where git comes from.

When it finishes it prints Next steps: run the lines it shows there. They put Homebrew on your PATH, the step most often missed.

Then tell git who you are. The agent's version history commits under this name, and fails without it:

git config --global user.name "Your Name" && git config --global user.email "you@example.com"

Your host

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Bun

Install from bun.sh. It adds itself to ~/.zshrc, but only when that file already exists; on a Mac without one it prints two lines to add instead, so run those.

uv and Python

Install uv from docs.astral.sh/uv (the standalone installer). It lands in ~/.local/bin and updates itself with uv self update. Then, in a new terminal:

uv python install --default

That installs the current Python and makes it python and python3 in your shell, leaving the system and Homebrew Pythons alone. uv keeps several versions side by side, and the agent runs its scripts through uv run. If it asks for --preview, add it.

Helpers

brew install poppler

Add gh to the line if you plan to turn on the GitHub pack. Attaching screenshots to issues needs gh 2.99 or later.

Check

Quit and reopen Terminal so the PATH changes load, then:

for c in git bun uv python3 claude; do v=$($c --version 2>/dev/null | head -1); printf '%-7s %s\n' "$c" "${v:-MISSING}"; done

Every line should show a version, and python3 should be uv's, not the system's 3.9. On Codex, swap claude for codex.