Most setup guides for AI coding tools stop at “install the CLI and run npm install.” That gets you a working agent, but it doesn’t get you an environment where running two or three agents at once won’t quietly cause problems — shared working directories, no isolation, a terminal that chokes on a wall of streaming output.
A macOS dev environment built for AI agents needs a few things a normal setup doesn’t: fast git isolation, a terminal that can keep up, and a workflow for reviewing what came back. None of it is exotic — most of these pieces are things Mac developers already have lying around — but it’s rarely assembled deliberately. This post walks through what to install and configure, in the order it actually matters.
Start With the Command-Line Basics
Before any AI tooling, make sure the foundation is there. Xcode Command Line Tools give you git, clang, and the other binaries most agent CLIs assume exist:
# Install Xcode Command Line Tools (git, clang, make, etc.)
xcode-select --install
# Install Homebrew, the package manager most setup guides assume
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Confirm git is present and check the version
git --version
Newer versions of macOS ship recent-enough git out of the box, but if git worktree behaves oddly, a Homebrew-installed git (brew install git) is worth having as a known-good fallback.
Configure Git for Isolation, Not Just Version Control
The single highest-leverage habit for a multi-agent setup is giving every agent session its own git worktree and branch rather than letting agents share your main working directory. Two agents editing the same checkout will eventually overwrite each other’s uncommitted work — it’s not a matter of if.
# From your main clone, create an isolated worktree for one agent's task
git worktree add ../myrepo-agent-auth -b agent/fix-auth-bug
# List every worktree currently attached to the repo
git worktree list
# Clean one up once the task is merged or discarded
git worktree remove ../myrepo-agent-auth
A consistent naming scheme for branches — something like agent/<short-task> — pays off quickly once you have four or five worktrees open; see git branch naming conventions for AI workflows for a fuller pattern to adopt.
Pick a Terminal That Can Keep Up
AI agents produce a lot of output fast — file listings, diffs, long log streams — and macOS’s default Terminal.app, along with several third-party terminals, renders that output on the CPU. Under heavy scrollback it visibly lags. A GPU-accelerated terminal like Ghostty or Alacritty renders text using the graphics card instead, which stays smooth even when an agent is dumping a large diff to the screen.
This matters more than it sounds like on paper. A terminal that stutters while an agent is mid-response makes it tempting to stop watching and just wait for “done” — which is exactly when you miss something worth interrupting for.
Manage API Keys and Environment Variables Safely
Most agent CLIs need at least one API key, and once you’re running several worktrees at once it’s tempting to copy a .env file into each new folder by hand. That’s both tedious and a good way to end up with stale keys scattered across old worktrees you forgot to clean up.
A cleaner pattern is to keep secrets in your shell profile or a dedicated secrets manager, not in per-project files that get duplicated with every git worktree add:
# In ~/.zshrc — loaded once, available in every new worktree's shell
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
# Reload after editing
source ~/.zshrc
This also sidesteps a subtler problem: a .env file sitting inside a worktree can accidentally get swept up in a commit if your .gitignore isn’t set up correctly for that specific folder. Keeping keys at the shell level means they never touch the repository at all.
Set Up Your Editor and SSH Once, Not Per-Worktree
A few one-time setup steps save repeated friction across every future worktree:
| Setup step | Why it matters for agents |
|---|---|
| SSH key added to GitHub/GitLab | Every new worktree can push without re-authenticating |
Global .gitignore includes editor/OS cruft |
Agent-created worktrees don’t pick up .DS_Store noise |
Editor CLI installed (code, cursor, or Xcode’s xed) |
Open any worktree in your editor with one command |
Global git identity set (user.name, user.email) |
Every agent-created commit is attributed correctly |
# Make sure your editor's CLI launcher is installed
# (VS Code: Cmd+Shift+P -> "Shell Command: Install 'code' command in PATH")
code ../myrepo-agent-auth
# Set your git identity once, globally
git config --global user.name "Your Name"
git config --global user.email "you@example.com"
Decide How You’ll Review What Agents Produce
The last piece — and the one people skip most often — is deciding before you’re mid-task how you’ll review an agent’s diff. Running git diff in a terminal works, but it doesn’t scale past one or two sessions a day. Whatever you choose, decide it now rather than improvising it under time pressure when three agents finish at once.
Keep Local-First Tools in the Mix
It’s worth being deliberate about how much of your setup depends on a remote service versus running on your own Mac. A dev environment built entirely around cloud dashboards and hosted CI is fine until the network is slow or a service has an outage in the middle of a task. Favoring local-first AI coding tools where you can — a terminal that runs locally, worktrees on local disk, a diff viewer that doesn’t round-trip to a server — keeps your environment fast and available no matter what’s happening upstream.
Common Setup Mistakes to Avoid
- Sharing one working directory across agents “just for this task.” It’s the single most common cause of one agent silently overwriting another’s edits — worth the thirty seconds it takes to spin up a worktree instead.
- Skipping the terminal upgrade because “it’s just a terminal.” The rendering difference is invisible until an agent streams a genuinely large diff, and by then you’ve already missed something scrolling past too fast to read comfortably.
- Leaving old worktrees around. Stale worktrees accumulate disk usage and clutter
git worktree listoutput until you can’t tell which one is active; prune them as soon as a task is merged. - Configuring everything per-project instead of once, globally. SSH keys, editor CLI links, and shell environment variables belong at the user level, not duplicated into every new clone.
Getting Started
- Install Xcode Command Line Tools and Homebrew if you haven’t already, then confirm
git --versionworks. - Create your first isolated worktree with
git worktree addand try running a single agent session in it, separate from your main checkout. - Swap your default terminal for a GPU-accelerated one and notice the difference the next time an agent streams a long diff.
- Once you’re running more than one agent at a time, Agents wraps all of this — worktrees, branches, a fast terminal, and a diff review panel — into one sidebar, with a free 7-day trial and a one-time $9.99 after that.
None of these pieces require exotic tooling — worktrees, a fast terminal, a consistent naming scheme — but assembling them deliberately, before you’re three agents deep into a real task, is what separates a dev environment that scales from one that quietly breaks under its own weight.