Set Up Your Mac
Here's how a "Set Up Your Mac" app sets up a software development environment. Everything is explained here.
First, I want to tell you why I created the "Set Up Your Mac" apps. Then I'll explain everything the app does for you.
I've taught beginners to code for years, since before AI. With any class, YouTube video, or how-to tutorial, there's always a big hurdle. No one says how to set up your Mac. It's even worse now, because we expect AI to help, but no one knows what questions to ask to get started.
It seems everyone's setup instructions always skip steps. The people who wrote them set things up so long ago, they've forgotten what needs to be installed first. As if you're supposed to know.
I wrote the apps, and provide this page, so nothing is skipped. A new Mac does not come ready for building software. Out of the box, it lacks the essentials developers need: Apple's Command Line Tools, a correctly configured command line, a package manager to install software tools, terminal and editor applications, and now, AI coding agents. Each essential depends on the ones before it, starting with the Mac's first secret, How to Open the Terminal.
If you want to set up your Mac for coding, start here. The "Set Up Your Mac" apps will do the work for you, step by step. Each step in the app links to Mac Install Guide, where I explain what it is about, why you need it, and point you to more resources if you want to learn more. It's like a course, but it's free, there's no homework, and the app will do all the work.
I promise, you don't need to know anything before you begin. This page will give you an overview if you followed a link from a "Set Up Your Mac" app. If you haven't yet installed a "Set Up Your Mac" app, you can find all of them on the Set Up Your Mac page. The Mac Install Guide home page gives a visual roadmap to every topic on this site.
Choose a Set Up Your Mac app
I built a family of "Set Up Your Mac" apps to match different needs: setting up your Mac for coding, for the command line, for Claude Code, for Python or for Java, or with Homebrew. They share one approach and many of the same tasks, so this page applies to whichever app you opened. Each app checks your Mac, shows you what it found, and offers to install and configure only what is missing. Then the app proves the result works.
Download the app
Really, there's nothing for you to do but download the app. Double-click the downloaded file to open it, drag the app to the Applications folder, then double-click the app to launch it. I recommend "Set Up Your Mac for Coding" unless you want something more specific. Here are all the details about the app before you download. Then download it:
Mac requirements for coding
First, check the macOS version. If you're running an older version, update macOS to the latest macOS version. Upgrading macOS is free on every Mac.
Mac requirements: You'll need a Mac with Apple Silicon running macOS 15 or later.
It is best to start any project with the newest macOS installed, so upgrade macOS if you're behind, unless you have an old and slow Intel-based Mac. See macOS compatibility.
Why you need Apple Silicon: Apple's macOS no longer supports Intel-based Macs from macOS 27 onward. You'll need Homebrew for installing software tools, and Homebrew no longer supports Intel Macs or older versions of macOS as of September 2026. On an older version of macOS, tools must be built from their source code, which is much slower and sometimes fails. On an Intel Mac, you can still install the Xcode Command Line Tools and use MacPorts as your package manager but you can't use the "Set Up Your Mac" apps because they need Homebrew.
App first steps
Here's a detailed description of the app's behavior, in case you wonder. Skip past this section if you want to know more about setting up the development environment. Or just run the app and click the link to Mac Install Guide that you will find on each screen, if you want to learn more about each setup task.
Answer two questions about experience and teamwork
Before it checks anything, the app asks how much coding experience you have, and whether you use your Mac on your own or with a team. Your answers adjust a few later steps. For example, if you have coding experience, the app offers an example coding project, and if you work on a team, it offers AI connections to Slack and Notion.
The app checks your Mac before anything changes
When you click the button labeled "Check my setup", the app looks for the Command Line Tools, your shell configuration, and Homebrew. Anything already working is skipped, so you only see the tasks your Mac still needs. More importantly, nothing on your Mac has changed yet, and nothing will change until you are informed and click a button that allows it.
Before installing, the app also checks for problems that make installs fail partway: a slow or unreachable internet connection, and low disk space. If it finds a risk, it warns you and lets you continue or stop. Stopping leaves your Mac exactly as it was.
Safety and integrity
Each task has its own screen that says what the task does and why, with one button to do it and another to skip it. You can skip anything, and the app moves on to the next task that still needs you. I designed every app to follow the same rules on every Mac:
- Configuration backups come first. Before the app changes a settings file, it saves a copy. It never overwrites lines that you or another tool wrote.
- Nothing is deleted or uninstalled. If a fix needs a file removed, the app shows you the command and leaves the decision to you.
- Your password goes only to macOS. When a task needs administrator rights, macOS asks for your Mac password in its standard dialog. The app never records passwords.
- Nothing runs in the background. When you quit, the app is gone until you open it again.
I want to know whether the apps are helpful and where they fail, so they send anonymous usage counts, such as "the check finished." They never identify you, never record your IP address, and never record passwords or file contents. See the privacy details for the full list.
When a password is needed
Some tasks (Command Line Tools and Homebrew) need administrator privileges. When they ask, you must enter the password you type to log in to your Mac. Your password never leaves your Mac. macOS asks for it in its own standard dialog, the same one it shows when you install other software.
When you set up a Mac or install an app from the App Store, Apple asks for your "Apple Account" password (formerly called the Apple ID). That's a different password from the password you use to log in to your Mac. The app never asks for it.
If you use a work Mac or an account without administrator rights, the app tells you before you start. You'll need to get help from the person with administrator privileges.
Checking disk space and internet connection
Some tasks download large files. If you install everything offered, setup can use almost 5 GB of disk space.
The first task, installing Command Line Tools, is usually the slowest download and can take many minutes. Apple's installer for the Command Line Tools asks for up to 12 GB of free space while it works, so clear some space first if your Mac is nearly full. While anything installs, the app shows its progress and adds a "Still working" line every 15 seconds. Keep the window open. If a download stalls or runs long, the app offers to keep waiting, try again, or skip.
Fix a failed install
Installs sometimes fail, most often because of the network, a full disk, or a mistyped password. When a download fails, the app explains the cause in plain words and offers to try again or skip. It also links to a Mac Install Guide article about the problem. For the Command Line Tools and Homebrew, it will show you the command to run, if you want to try yourself.
Don't skip the Command Line Tools (CLT) installation, even though it takes the longest. If CLT is not installed, in most cases the app ends with "Setup didn't finish" instead of completing the setup.
The app will verify your setup works
After setting up basic tools (Command Line Tools and Homebrew), the app checks that they really work. It opens a fresh shell, the same way a new terminal window does, and confirms that the Command Line Tools and Git work. Then it tells you your foundation is ready and asks whether you want to keep going.
You can stop there with a working foundation, or keep going to add AI coding tools, editors and languages. Keep going or run the app again whenever you like. Next time it runs, it doesn't repeat work; it offers only what is still missing, so nothing is installed twice. At the end, the app lists everything installed and working, with buttons to open each new app and any example project.
The essentials every developer needs
The most difficult part of setting up a Mac for coding is knowing what to do first, once you learn what essentials are needed. The app installs tools in a specific order so it can verify everything works with prior requirements properly installed.
Install Xcode Command Line Tools
Out of the box, a Mac doesn't contain the software developers need for programming. Apple provides it in Xcode, a huge app for building iPhone and Mac apps, but you don't need the entire Xcode package unless you plan to make apps for Macs, Apple phones and tablets, and the other Apple devices. Instead, smart developers install the Xcode Command Line Tools, or Xcode CLT, a much smaller package from Apple. It includes Git (for version control, explained later), the compilers that turn source code into working programs, and other essential tools that almost every developer tool expects. Homebrew, programming languages and many other tools depend on Xcode CLT, so without the Command Line Tools, the app will not finish setup.
Here's how the app handles the Xcode CLT installation and possible problems. It asks Apple's Software Update mechanism for the newest Xcode CLT version and installs it, after one password prompt. If your Xcode CLT is damaged, which can happen after a macOS upgrade, the app reinstalls it. If you have the full Xcode installed but haven't accepted its license, the app shows you Apple's license to read and accept, because Homebrew can't install anything until you do.
Configure your shell (.zprofile and .zshrc)
The shell is the program inside a terminal application that reads the commands you type. On a Mac, we use a shell program named zsh (Linux uses bash). When you open a terminal window, zsh reads a few settings files in your home folder. One of them sets your PATH, the list of folders where the shell looks for programs. If a tool's folder isn't on your PATH, the shell can't find it, and you'll see command not found even though the tool is installed. See Shell Configuration and Mac Path for the details.
The app prepares three files in your home folder (the ~ at the start of each name), backing up each one first:
~/.zprofilesets your PATH. The app adds a line that stops folders being listed twice, and later tasks add their own tool's folder here. Claude Code reads this file when it runs commands, so your AI agent finds the same tools you do.~/.zshrcholds settings for the terminal you type in, such as command completion, and loads~/.env.~/.envis a private file for API keys, the secret codes that let a tool use a third-party service. It starts with placeholder lines but no real keys, so it is ready whenever you set up a third-party service that needs an API key. You can use an editor app to add API keys later.
I recommend keeping the PATH in ~/.zprofile and terminal settings in ~/.zshrc, and the app follows that rule. To learn why, see .zshrc or .zprofile. Some developers (especially coming from Linux) only use the ~/.zshrc file but the article explains why Mac users need both files.
Install Homebrew
Homebrew is the package manager most Mac developers use. It is like an app store for programming tools (but everything is free): one short brew command installs, updates or removes software, instead of installers you download from websites. You'll need it for nearly everything that follows, including the terminal, AI tools, editors and languages. Homebrew also keeps all its installed packages up to date in one place.
The app runs Homebrew's official installer and adds Homebrew to your PATH in ~/.zprofile, the shell configuration step that is often overlooked and easy to get wrong. If Homebrew is already installed but your shell can't find it, the app fixes only the PATH. If an old copy sits in the location used on Intel Macs, the app installs the correct one for Apple Silicon and leaves the old one alone. You can skip Homebrew, but I don't recommend it, because most later tasks need it. If you'd rather do it yourself, see How to Install Homebrew on Mac.
Homebrew needs a little upkeep. If it hasn't refreshed its list of available software in the last day, the app offers to refresh it. It also shows four commands you can run yourself to keep Homebrew tidy: brew outdated, brew upgrade, brew autoremove and brew doctor. On macOS 26.2 or later, the app offers BrewUI, Homebrew's own app for finding and installing software. BrewUI isn't yet a full-fledged App Store for free software but it is useful as a Homebrew GUI app. Here is my own list of recommended free software available from Homebrew.
Choose a terminal application for Mac
A terminal application is the window where you type commands (think of the computer screens hackers use in movies). Apple includes its own Terminal, and it is adequate but a bit dated and cumbersome. Many developers prefer a terminal with more help built in. You'll use it to run commands, read error messages and, often, to work with an AI agent, so a friendlier terminal makes all of that easier to learn. I prefer Warp, a fast terminal application with AI to help you learn and remember commands, and the app offers to install it with Homebrew. If you'd rather use another terminal application, skip Warp and see Best Terminal for Mac to compare other choices.
Add the tools for building software with AI
With the foundation in place, you can add the tools for building software with AI. All of these are optional, so take what you need now and come back for the rest later.
An AI coding agent is a program that examines your project, writes and edits code, and runs commands for you, while you describe what you want in plain words. The tools in this part give an agent a place to work and the information it needs.
Before AI agents took over the work of writing code, an aspiring software developer needed to spend months learning the rules and commands of a programming language such as Python or Java, and then years learning the art of good programming practices. Now anyone can "vibe code" because the AI agents can take our requests and turn them into software applications. Of course, you need to know how to set up your Mac, which is what "Set Up Your Mac" apps will do. And you'll be more successful if you learn the practices of software engineering and product management, which is what you can study once your Mac is set up and AI agents are ready to write your code.
Install Claude Code and Codex
Claude Code, from Anthropic, and Codex, from OpenAI, are two widely used AI coding agents. Each comes in two forms: a desktop app, and a command-line tool (CLI) that runs in your terminal. Having both forms lets you work whichever way suits the task. The agent is what lets you build software by describing it, but there are important "extras" that most developers use to guide and extend the capabilities of the AI agents. This app will set up the extras, which require files in key places and configuration tweaks that are difficult to get right.
After you choose Claude Desktop and the Claude Code CLI, you can add the ChatGPT desktop app (which includes Codex, OpenAI's coding harness) and the Codex CLI. All of them install using Homebrew. To install them yourself, see Install Claude Code on Mac and ChatGPT for Mac.
Claude Desktop and the ChatGPT desktop app are free to install. You can do coding with Codex inside the ChatGPT desktop app but you'll soon need to upgrade to the $20/month plan to finish any sizeable project. You can use Claude Desktop for chat for free and even write project planning files, but Claude Code itself needs a paid Claude plan, starting at $20/month (see What's Needed to Run Claude Code). You can get started with coding by asking questions in the free browser chat platforms but you can't do much without at least a $20/month plan that gives you the full Claude Code or OpenAI Codex applications. Coding isn't free because the AI agents need to run their inference engines in expensive data centers.
Think of your coding journey like this: In the pre-AI days you'd set up your Mac with a terminal and editor and begin learning a programming language from a book or a course. Now you start by asking the AI questions in a web browser, install an AI desktop app, an in-terminal CLI app, or both, pay a subscription to get enough tokens to get something done, and learn "vibe engineering" with guidance from the AI agent and YouTube videos.
Create a project folder for your AI agent
Any project lives in a folder (directory) that holds all the files needed to accomplish the project goals. Computers have always relied on files and folders and it is no different in the age of AI. An AI agent works best inside a project folder, where it doesn't have to read irrelevant files and its changes stay contained.
You can authorize the AI agent to create a folder and preliminary files with a chat prompt, but it is better to start with a project and files that lay the groundwork for good vibe engineering practices.
The "Set Up Your Mac" apps give you a ready-made project, so your agent gets started with good practices right away. Choose a folder for the example project, or let the app put it in your Documents folder. The project includes instruction files named CLAUDE.md and AGENTS.md, which give the AI agent rules about the project. If you have coding experience, you also get an example coding project.
Examine the files in the example project to get an idea of how to organize a new project for good vibe engineering.
Add skills to Claude Code and Codex
A skill is a packaged set of instructions, sometimes with a small program, that teaches an AI agent to do a particular job well. Skills let your agent do useful jobs from the first day, without long instructions from you each time. To see the skills you have, type / (slash) in a chat with your agent.
I picked a few skills for the app to offer, such as one that makes your agent's writing sound less like a machine and one that tidies your Downloads folder after showing you a preview. Accept one and the app copies it into the folders that Claude Code and Codex read. You'll learn about more skills from YouTube videos or blog posts and you can ask the AI agent to add skills to your project.
Connect MCP servers to Claude Code and Codex
MCP stands for Model Context Protocol, a standard way to connect an AI agent to other tools and services. An MCP server is a small connector: one might let your agent read web pages cleanly, and another might let it read your team's documents. For example, an agent that reads the web on its own often gets raw page code, a blocked page, or nothing at all, but a web-reading MCP server gives it clean page text.
For web reading, the app offers Jina Reader and Firecrawl. Jina Reader needs a free API key, and Firecrawl works without one. If you said you work on a team, the app also offers MCP connections to Notion and Slack. Each uses your own sign-in, so your agent only sees what you can see. Keys are saved only in your agent's settings file. Restart Claude or Codex afterward to load the new servers.
You can ask the agent to add an MCP server if you find one that you want to use.
Install a Markdown editor
Markdown is a simple way to format plain text with a few symbols, such as # for a heading and - for a list item. AI tools use it for their instruction files, such as CLAUDE.md, and for plans and notes. You'll read and edit these files often. A code editor can open them, but a Markdown editor shows them as formatted text, without the markup symbols, which is easier to read.
Markdown files are the glue that holds together any project, especially planning documents and the files you save as you go that give an AI agent context and memory beyond short-lived chat sessions. Increasingly, in the age of AI, a Markdown editor is becoming more important than a code editor, especially for the human's role in AI-driven software development.
For Markdown, the app offers ColaMD, a free editor that shows Markdown as formatted text.
Choose a code editor for Mac
A code editor is an app for reading and writing code (you can't write code with Microsoft Word because its hidden formatting gets in the way). It formats code so it is easier to read, lists the files in a project, and shows exactly what changed. Even when an AI agent writes the code, you need a place to see and check what it wrote. Many editors have AI agents built in for coding assistance so you'll make a choice of whether to interact with AI agents in a code editor, a terminal command line, or in the AI desktop app.
The choice is yours. The app offers four well-known editors: Zed, Cursor, Devin Desktop (formerly Windsurf) and VS Code. Install one or several.
Install Python and other languages with a version manager
A programming language such as Python or JavaScript must be installed before you can run programs written in it. However, projects often need different versions of a language, and two installers for the same language can conflict. That's why I recommend a version manager: a tool that installs a language and lets you switch between its versions, one project at a time. Use one version manager per language and you'll avoid a mess that is hard to undo.
You pick the languages you want. The app installs Python with uv, JavaScript (Node) and Ruby with mise, Rust with rustup or mise, and Java from Homebrew with JAVA_HOME set. If another version manager already manages a language, the app warns you before installing. See Python on Mac, Java on Mac and Mise on Mac to learn more.
Add a global CLAUDE.md and AGENTS.md
AI coding agents read instruction files at the start of every session. A global instruction file, which applies to all your projects, is the place to describe your Mac. An agent that doesn't know your setup may guess, for example by installing a second copy of Python or changing your PATH. A short note tells it which tools you use and how they were installed.
The app adds a short, clearly marked note to ~/.claude/CLAUDE.md for Claude Code and ~/.codex/AGENTS.md for Codex, describing how Homebrew, uv and mise are set up. It keeps your existing instructions and backs them up first.
Set up Git and GitHub
Git is version control for save-as-you-go backups of your work. It saves snapshots of your project, called commits, so you can see what changed and go back to any earlier version. GitHub is a website that stores copies of your Git projects in the cloud and lets you share them. More importantly, when an AI agent edits many files at once, Git is your undo button. Ask the agent to make a commit before and after each task, and you can always ask the agent to return to a version that worked.
The app helps you set the name and email that Git records with each commit, installs GitHub's command-line tool, gh, and signs you in to GitHub in your web browser, so you don't have to type a password each time. The app never sees your GitHub password. If you don't have a GitHub account yet, the app links to the sign-up page, and you can finish signing in later with gh auth login. See Git Config for the settings in detail.
It might seem like an unnecessary extra, but every coder uses Git and GitHub (or another similar service) because there's no better way to save your work as you go or collaborate on a team.
What to learn next
A setup app installs and configures tools, but it can't teach you to use them. Here are topics you should learn next. You can read about them on the Mac Install Guide website or ask your AI agent to explain.
Learn terminal basics
You'll use a terminal application to check that tools work and to follow instructions you find online. Learn how to open a terminal application, then try three commands: pwd shows which folder you are in, ls lists its files, and cd moves to another folder. See Mac Terminal for a gentle introduction.
Two things surprise many beginners. When instructions show a command with a $ in front, the $ stands for the prompt, so don't type it. It is just a convention that indicates you are expected to enter a command in the terminal.
Also, when you type a password in a terminal application, nothing appears on screen, not even dots. That is normal: type it and press Return.
Warp Terminal has built-in AI to explain commands so you can learn as you go. Or ask an agent in chat to explain terminal commands.
Fix "command not found" after installing a tool
A terminal window reads your settings files only when it opens. After installing a tool, open a new terminal window before you use it. If you still see command not found, the tool's folder is probably missing from your PATH. See Command not found for the fix.
Safety with terminal commands
Commands you are told to enter from websites, videos and AI assistants can change or delete files with no undo. Before you press Return, look for these warning signs:
sudoruns a command with administrator rights over the whole Mac.rmdeletes files permanently, without using the Trash.- Anything aimed at
~(your home folder) or/(the whole disk) affects everything inside it. - A command that downloads a script and runs it at once, such as one containing
curland| sh, runs code you haven't seen.
Some of these are normal (Homebrew's own installer downloads a script and runs it). Copy install commands only from a tool's official website. If you don't understand a command, ask your AI assistant to explain it before you run it.
Use an AI coding agent safely
An AI agent can edit, move and delete files. Start the agent inside a dedicated project folder, never from your home folder. Make a Git commit before and after each task you give the agent, so any change is easy to undo. Finally, learn where your agent's permission settings are. They control what it may do without asking, such as editing files or running commands.
Push your work to GitHub before you start and as you go. Anything you mark to save ("commit") in a Git-enabled folder can be recovered, but changes you haven't committed aren't saved. For extra protection, if you have an external backup disk, turn on Time Machine, the backup feature built into macOS (System Settings > General > Time Machine), so you can recover anything that goes wrong.
Keep API keys and passwords private
API keys and passwords give access to your accounts, and a stolen key can run up charges. The ~/.env file the app creates is a reasonable place for an AI service's API key. Keep other passwords in a password manager. Never put keys in your project's files or paste them into an AI chat, and set a spending limit on any paid API key.
Choose a Claude or ChatGPT plan
My apps and the AI coding tools are free to install, but the AI services need an account. Claude Code needs a paid Claude plan. You can also pay for each use with an API key instead of a monthly plan, either directly from Anthropic or OpenAI, or through a service such as OpenRouter. Compare the plans on each company's website before you subscribe, and check how their usage limits work.
Show hidden files on Mac
Settings files such as ~/.zprofile start with a dot, which hides them in the Finder. Press Command + Shift + . (period) in a Finder window to show them. See Show Hidden Files on Mac, and Finder Settings for a New Mac for other settings developers change, such as showing filename extensions.
Learn Markdown basics
The app installs a Markdown editor but doesn't teach Markdown. Fortunately, a few symbols cover most needs: # for headings, - for list items, ** around bold text, and backticks around code. A short Markdown guide is enough to read and edit your agent's instruction files.
Update Homebrew and your tools
Tools need updates to stay secure and work with each other. Run brew outdated to see what Homebrew can update, and brew upgrade to update it (see Housekeeping for Homebrew). After each macOS upgrade, check that your Command Line Tools are current. Once the app has set it up, Claude Code keeps itself up to date (see Update Claude Code).
Troubleshoot a failed command
When a command fails, read the error message slowly, because it usually names the problem. Copy the exact message into a search engine or your AI assistant, along with what you were trying to do. I've written pages for many common errors, such as zsh: command not found: brew. Running your Set Up Your Mac app again is another quick check, because it finds and offers to fix problems with the foundation.
Continue setting up your Mac
Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.