The Setup
Everything you need to start building. Nothing more.
What You Need
Four things:
-
A Mac — This guide assumes macOS. The concepts translate to other platforms, but the specifics are Mac-focused.
-
Claude Code — Your AI building partner. This is how you’ll communicate with Claude while building.
-
A code editor — VS Code or Cursor. Both are free. You’ll use this to look at files and make occasional direct edits.
-
Xcode — Apple’s development environment. Free from the App Store. Required for building macOS and iOS apps.
That’s it. No frameworks to install. No languages to learn first. No complex toolchains to configure.
What It Costs
Let’s be upfront about this.
- Claude Pro or Max subscription — Required for Claude Code. Pro is $20/month, Max is $100/month (for heavier usage). This is your main ongoing cost.
- Apple Developer Program — $99/year. Only needed if you want to publish to the App Store or distribute macOS apps outside the Mac App Store. Not needed for learning or building for yourself.
- Hosting (Vercel/Netlify) — Free tier covers most personal projects. You only pay if you get significant traffic.
- Xcode — Free from the Mac App Store. Required for macOS and iOS projects.
- Everything else — Node.js, Git, VS Code/Cursor — all free.
You can get started for as little as $20/month (Claude Pro). Everything else is either free or optional until you’re ready to publish.
Installing Claude Code
Claude Code is a command-line tool. That might sound intimidating, but it’s simpler than it seems. See the official setup guide for the latest installation instructions.
Step 1: Open Terminal
Terminal is already on your Mac. Find it:
- Press
Cmd + Spaceto open Spotlight - Type “Terminal”
- Press Enter
You’ll see a window with a text prompt. This is just another interface — like Finder, but text-based.
Step 2: Install Claude Code
Copy and paste this command into Terminal, then press Enter:
curl -fsSL https://claude.ai/install.sh | bashThis is the recommended installation method. It installs Claude Code and keeps it automatically updated.
Step 3: Verify It Works
Type:
claude --versionYou should see a version number. Claude Code is installed.
Step 4: Authenticate
Type:
claudeThe first time you run it, you’ll be prompted to authenticate. Follow the prompts — it’ll open a browser window. You’ll need a Claude Pro or Max plan, or an Anthropic Console account with billing set up. See the official authentication docs for all options.
Once authenticated, you’re ready.
The Terminal Isn’t Scary
Let’s address this directly: the terminal is just a text-based interface. That’s all.
You already use text-based interfaces constantly — search bars, chat apps, address fields. Terminal is the same concept applied to your computer’s file system.
You’ll need about five commands total:
| Command | What it does | Example |
|---|---|---|
cd | Change directory (folder) | cd ~/Desktop |
ls | List files in current folder | ls |
pwd | Print current location | pwd |
open | Open a file or folder | open . |
claude | Start Claude Code | claude |
That’s it. When you need to do something else, ask Claude: “How do I [X] in terminal?” It’ll tell you.
Quick orientation
When you open Terminal, you’re “in” a folder — usually your home folder. The prompt shows where you are.
# See where you are
pwd
# See what's here
ls
# Go to Desktop
cd ~/Desktop
# Go back home
cd ~The ~ symbol means your home folder. ~/Desktop means the Desktop folder inside your home folder.
Installing a Code Editor
You need somewhere to look at code files. Two good options:
VS Code (recommended for beginners)
- Download from code.visualstudio.com
- Drag to Applications
- Open it once to set up
Cursor (if you want AI features built in)
- Download from cursor.sh
- Same installation process
- Has additional AI features, but Claude Code is your primary tool
Either works. Pick one and install it.
Opening folders in your editor
From Terminal, you can open the current folder in VS Code:
code .Or in Cursor:
cursor .The . means “current folder.”
Installing Xcode
Xcode is Apple’s development environment. You need it to build macOS and iOS apps.
- Open the App Store
- Search for “Xcode”
- Click “Get” (it’s free, but large — ~12GB)
- Wait for it to download and install
After installation, open Xcode once. It’ll ask to install additional components. Say yes and let it finish.
You won’t use Xcode directly very often — Claude Code handles most of the interaction. But it needs to be installed for building apps.
How Projects Are Structured
Before we go further, let’s demystify what a “code project” actually is.
A project is just a folder. Inside that folder are files. Some files contain code. Some contain configuration. Some contain assets like images.
my-app/
├── README.md ← Description of the project
├── Package.swift ← Configuration (what the project needs)
├── Sources/
│ └── MyApp/
│ ├── App.swift ← Code files
│ ├── Views/
│ │ └── MainView.swift
│ └── Models/
│ └── User.swift
└── Resources/
└── icon.png ← AssetsYou don’t need to understand every file. Claude does. Your job is to:
- Know roughly where things are
- Describe what you want to change or add
- Review what Claude creates
Think of it like a building: you don’t need to know how the electrical system works to live there. You need to know where the light switches are.
Your First CLAUDE.md
Here’s something powerful: you can give Claude context about your project that persists across conversations.
Create a file called CLAUDE.md in your project folder. This file tells Claude what it needs to know.
# My App
## What This Is
A simple menu bar app that shows the current time in different timezones.
## Tech Stack
- macOS app (SwiftUI)
- Menu bar presence
- No external dependencies
## Current State
Just starting. Basic structure exists.
## Conventions
- Keep it simple
- Prefer SwiftUI native components
- No over-engineeringWhen you run claude in that folder, it automatically reads this file. Claude knows what you’re building, what technologies you’re using, and what your preferences are.
We’ll cover CLAUDE.md in more detail later. For now, know that it exists.
See Templates for starter templates.
The “Just Ask” Test
Let’s prove this all works.
Step 1: Create a test folder
mkdir ~/Desktop/claude-test
cd ~/Desktop/claude-testStep 2: Start Claude
claudeStep 3: Ask it something
Type:
Create a simple hello world HTML file
Claude will create a file. It’ll show you what it’s doing.
Step 4: See the result
open .This opens the folder in Finder. You should see an HTML file. Double-click it — it’ll open in your browser.
You just built something. That’s the whole loop: describe what you want, Claude creates it, you review the result.
Step 5: Iterate
Back in Claude, type:
Make the text bigger and change the color to blue
Claude modifies the file. Refresh your browser. See the change.
This is the workflow. You’re ready.
Checklist
Before moving on, confirm:
- Claude Code installed and authenticated
- Code editor installed (VS Code or Cursor)
- Xcode installed
- “Just Ask” test completed successfully
Troubleshooting
Things go wrong. Here’s how to fix the common ones. See also the official troubleshooting guide.
”claude: command not found” (after installing)
Close and reopen Terminal, then try again:
claude --versionStill not working? Run the installer again:
curl -fsSL https://claude.ai/install.sh | bashIf you previously installed via npm, migrate to the native installer:
claude installAuthentication fails or loops
If the browser auth doesn’t complete:
- Make sure you’re logged into claude.ai in your browser
- Verify you have a Claude Pro or Max plan or Anthropic Console billing set up
- Try a different browser if one isn’t working
- Check that popups aren’t blocked
If it keeps asking you to authenticate:
# Clear Claude's stored credentials and start fresh
rm -rf ~/.claude
claude“code .” or “cursor .” doesn’t work
The editor command isn’t installed.
For VS Code:
- Open VS Code
- Press
Cmd + Shift + P - Type “shell command”
- Select “Shell Command: Install ‘code’ command in PATH”
For Cursor:
- Open Cursor
- Press
Cmd + Shift + P - Type “shell command”
- Select the install option
Xcode “additional components” won’t install
Open Xcode directly and accept any prompts. If it’s stuck:
# Force Xcode to set up its tools
sudo xcodebuild -license accept
xcode-select --install“Just Ask” test creates nothing
Claude responded but no file appeared? Check:
- Are you in the right folder? Run
pwdto see where you are - Did Claude say it would create a file, or just describe what to do?
- Try being more explicit: “Create a file called hello.html with a basic HTML page”
Still stuck?
Try running claude doctor — it checks your installation and reports common issues.
You can also describe exactly what happened:
- What command you ran
- What you expected to happen
- What actually happened (copy the error message)
Paste this into Claude Code — it can diagnose most issues. Or check the official troubleshooting guide and Claude Code GitHub issues.