Set Up Claude Code on Mac

Installing Claude Code on macOS

This lesson walks you through a complete Claude Code installation on macOS — from Node.js to your first conversation.

Step 1: Verify Node.js

node --version
# Requires v18.0.0 or higher

If you need to install Node.js, Homebrew is the fastest option:

brew install node@20

Or use nvm for version management:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.zshrc
nvm install 20

Step 2: Install Claude Code Globally

npm install -g @anthropic-ai/claude-code

Verify the installation:

claude --version

Step 3: Authenticate

You have two options:

Option A — Claude Pro/Team subscription (recommended):

claude
# Follow the browser login prompt
# Claude Code will open your browser for OAuth
# Log in with your Anthropic account

Option B — API key:

export ANTHROPIC_API_KEY=sk-ant-xxxxx
claude

Add the export to your ~/.zshrc to persist across sessions:

echo 'export ANTHROPIC_API_KEY=sk-ant-xxxxx' >> ~/.zshrc
source ~/.zshrc

Step 4: First Run Walkthrough

Navigate to any project directory and launch Claude Code:

mkdir ~/test-project && cd ~/test-project
claude

You will see the Claude Code prompt. Try these commands:

> /help          # See all available commands
> /status        # Check connection and model info
> /model         # See or change the active model
> Hello, what can you do?   # Start a conversation

Step 5: Understanding the .claude Directory

After your first run, Claude Code creates a configuration directory:

~/.claude/
├── settings.json     # Global settings
├── commands/         # Personal custom slash commands
└── credentials       # Auth tokens (never share this)

Project-level configuration lives in your project root:

your-project/
├── .claude/
│   └── commands/     # Project-specific commands
├── CLAUDE.md         # Project context file
└── ...

Common macOS Issues

"Permission denied" during global install:

npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

"claude: command not found" after install:

# Check where npm installed it
npm list -g --depth=0
# Add the npm global bin to PATH if needed
export PATH=$(npm config get prefix)/bin:$PATH

Slow performance or timeouts: Check your internet connection. Claude Code requires a stable connection to the Anthropic API. If you are behind a VPN, try disconnecting temporarily.

Key Takeaways

• Install Claude Code with npm install -g @anthropic-ai/claude-code
• Authenticate via browser login (Pro subscription) or API key (environment variable)
• The ~/.claude/ directory stores global settings and credentials
• Each project can have its own .claude/ directory for project-specific configuration
• Always verify your installation with claude --version before starting a project