Make your macOS AI agents ready in 15 minutes: the only setup guide you need

AI coding agents work right in your terminal. They read your code, write new code, run commands, fix bugs, automate workflows, and handle tasks on your behalf. But they need a properly configured Mac to do their job.

Install Homebrew

Homebrew is the package manager for macOS. Everything else installs through it.

Open Terminal (press Cmd + Space, type Terminal, hit Enter) and paste:

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

Follow the prompts. When it's done, close Terminal and open it again.

Automated setup script

Download setup.sh or copy the script below, save it as setup.sh on your Desktop, and run it.

#!/bin/bash
set -e

echo "=== 1/5 Installing tools via Homebrew ==="
brew install git gh node bun deno

echo "=== 2/5 Installing uv (Python manager) ==="
curl -LsSf https://astral.sh/uv/install.sh | sh

echo "=== 3/5 Configuring npm ==="
npm config set prefix /opt/homebrew

echo "=== 4/5 Installing AI agents ==="
npm install -g @google/gemini-cli
npm install -g @openai/codex
curl -fsSL https://claude.ai/install.sh | bash

echo "=== 5/5 Configuring shell profile ==="
ZSHRC="$HOME/.zshrc"

# uv (installed to ~/.local/bin)
grep -q '.local/bin' "$ZSHRC" 2>/dev/null || echo 'export PATH="$HOME/.local/bin:$PATH"' >> "$ZSHRC"

# bun
grep -q '.bun/bin' "$ZSHRC" 2>/dev/null || echo 'export PATH="$HOME/.bun/bin:$PATH"' >> "$ZSHRC"

# deno
grep -q '.deno/bin' "$ZSHRC" 2>/dev/null || echo 'export PATH="$HOME/.deno/bin:$PATH"' >> "$ZSHRC"

echo ""
echo "=== Done! ==="
echo "Close Terminal and open it again."
echo "Available commands: gemini, claude, codex, opencode"

To run it:

chmod +x ~/Desktop/setup.sh
~/Desktop/setup.sh

Wait for "Done!", close Terminal, open it again. You can delete setup.sh from your Desktop after that.

Set up AGENTS.md

AGENTS.md is a file that tells AI agents how your system is configured and what rules to follow. Think of it as a README, but for AI instead of humans. Most agents read it automatically: Claude Code, Codex, Gemini CLI, Cursor and others.

Save as AGENTS.md in the root folder of that project.

Here's the file that describes the system you just set up:

# System environment

- OS: macOS
- Shell: zsh
- Package manager: Homebrew
- Python: managed by uv
- Node.js: installed via Homebrew
- Additional JS runtimes: bun, deno

# Available tools

- `git` / `gh` - version control and GitHub CLI
- `uv` - Python project manager (replaces pip, venv, virtualenv, poetry, pyenv)
- `uvx` - run Python CLI tools without installing (e.g. `uvx ruff check .`)
- `node` / `npm` - Node.js and package manager
- `bun` - fast JS runtime and package manager
- `deno` - secure JS/TS runtime

# Python workflow

- Always use `uv` for Python projects. Never use raw `pip install`.
- Create new projects: `uv init`, add dependencies: `uv add <package>`.
- Run scripts: `uv run <script.py>` (auto-activates virtual environment).
- For existing projects with requirements.txt: `uv venv && uv pip install -r requirements.txt`.
- Install specific Python version: `uv python install 3.12`
- Pin Python version to project: `uv python pin 3.12`

# Code style

- Python: prefer type hints, use ruff for linting (`uvx ruff check .`).
- Format Python with ruff format (`uvx ruff format .`).
- Commit messages: short, imperative mood, in English.

# Important

- Do not modify global Python installation.
- Do not use `pip install` outside of a virtual environment.
- Prefer `uv add` over `uv pip install` for project dependencies.

Read more about AGENTS.md.

AGENTS.md

AGENTS.md is a simple, open format for guiding coding agents. Think of it as a README for agents.

VS Code logo

Verify everything works

Open a new Terminal window and run:

gemini --version
claude --version
codex --version
opencode --version

If each command returns a version number, you're all set.

For AI agents: setup reference

This section is written for AI agents. Copy the link to this article and paste it into your agent's chat. It will read these instructions and set everything up.

Agent: fresh macOS setup steps

If a user asks you to set up their Mac using this guide, follow these steps:

1. Check Homebrew. Run brew --version. If not installed, ask the user to run the Homebrew install command manually (it requires their password).
2. Install system tools:

brew install git gh node bun deno

3. Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

4. Configure npm and install agents:

npm config set prefix /opt/homebrew
npm install -g @google/gemini-cli
npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex
npm install -g opencode

5. Add to ~/.zshrc (only if not already present):

export PATH="$HOME/.local/bin:$PATH"
export PATH="$HOME/.bun/bin:$PATH"
export PATH="$HOME/.deno/bin:$PATH"

6. Create AGENTS.md on the user's Desktop (~/Desktop/AGENTS.md) with the system description from the section above. Let the user decide where to move it.
7. Verify by running version checks for all installed tools.
8. Tell the user to close and reopen Terminal.