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.
Three things:
-
A Windows PC — This guide covers Windows 10 or 11. You’ll use PowerShell or Windows Terminal.
-
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.
That’s it. No frameworks to install. No languages to learn first. No complex toolchains to configure.
Note: Xcode is not needed on Windows. Xcode is only required for building macOS and iOS apps. Windows users can build web apps, cross-platform desktop apps (Electron, Tauri), and more.
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 TerminalPowerShell
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.
PowerShell is already on your PC. Find it:
- Press the Windows key
- Type “PowerShell” or “Terminal”
- Press Enter
You’ll see a window with a text prompt. This is just another interface — like File Explorer, but text-based.
Tip: Windows 11 includes Windows Terminal, which is a nicer experience. Search for “Terminal” instead of “PowerShell” if you have it.
Step 2: Install Claude Code
Copy and paste this command into TerminalPowerShell, 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.
irm https://claude.ai/install.ps1 | iexThis 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 TerminalCommand Line Isn’t Scary
Let’s address this directly: the terminalcommand line is just a text-based interface. That’s all.
You already use text-based interfaces constantly — search bars, chat apps, address fields. TerminalPowerShell 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 |
| Command | What it does | Example |
|---|---|---|
cd | Change directory (folder) | cd ~\Desktop |
ls | List files in current folder | ls |
pwd | Print current location | pwd |
start | Open a file or folder | start . |
claude | Start Claude Code | claude |
That’s it. When you need to do something else, ask Claude: “How do I [X] in terminalPowerShell?” It’ll tell you.
Quick orientation
When you open TerminalPowerShell, 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.
# See where you are
pwd
# See what's here
ls
# Go to Desktop
cd ~\Desktop
# Go back home
cd ~The ~ symbol works in PowerShell and means your home folder (C:\Users\YourName). ~\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
VS Code (recommended for beginners)
- Download from code.visualstudio.com
- Run the installer
- Check “Add to PATH” during installation (important!)
Cursor (if you want AI features built in)
- Download from cursor.sh
- Run the installer
- Has additional AI features, but Claude Code is your primary tool
Either works. Pick one and install it.
Opening folders in your editor
From TerminalPowerShell, 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.
A Note on Xcode
Xcode is Apple’s development environment for macOS and iOS apps. It’s not available on Windows and not needed for Windows development.
On Windows, you can build:
- Web apps — React, Svelte, vanilla JS (deploy anywhere)
- Desktop apps — Electron or Tauri (cross-platform)
- APIs and backends — Node.js, Python, etc.
If you’re interested in macOS or iOS projects in this guide, you’d need a Mac for those specific projects. But the web projects work on any platform.
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-engineering# My App
## What This Is
A simple web app that shows the current time in different timezones.
## Tech Stack
- Web app (React + Vite)
- No external dependencies beyond React
## Current State
Just starting. Basic structure exists.
## Conventions
- Keep it simple
- Use modern CSS
- 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-testmkdir ~\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.
start .This opens the folder in File Explorer. 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
- Claude Code installed and authenticated
- Code editor installed (VS Code or Cursor)
- “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 installClose and reopen PowerShell, then try again:
claude --versionStill not working? Run the installer again:
irm https://claude.ai/install.ps1 | iexAuthentication 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# Clear Claude's stored credentials and start fresh
Remove-Item -Recurse -Force "$env:USERPROFILE\.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
For VS Code:
- Reinstall VS Code and check “Add to PATH” during installation
- Or: Open VS Code, press
Ctrl + Shift + P - Type “shell command”
- Select “Shell Command: Install ‘code’ command in PATH”
For Cursor:
- Open Cursor
- Press
Ctrl + 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 --installPowerShell execution policy error
If you see “running scripts is disabled on this system”:
# Run this in PowerShell as Administrator:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserThis allows locally-created scripts to run. It’s a safe, standard setting.
”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.