How to Set Up Claude Code on Mac

Claude Code Mac setup takes under 15 minutes when you follow the macOS-specific path. The generic installation guide skips the details that trip up Mac users: Apple Silicon PATH issues, Homebrew configuration, and Zsh shell differences.

This guide walks through every step, from Node.js installation to your first Claude Code session. Common macOS errors are addressed before you encounter them.

Key Takeaways

• Homebrew is recommended: It handles Apple Silicon compatibility and PATH configuration better than the standalone Node.js installer.
• Both Mac architectures work: Claude Code has no architecture restriction on M1/M2/M3 or Intel Macs.
• Zsh is your shell config: On macOS Catalina and later, configure PATH in ~/.zshrc, not ~/.bash_profile.
• Auth opens in your browser: Safari works fine; set your preferred browser as default before first launch.
• CLAUDE.md matters most: This 20-minute setup step determines Claude Code output quality more than anything else.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

What You Need Before You Start

You need four things before running the installation: a supported macOS version, Terminal, an Anthropic account, and Homebrew. Each takes under two minutes to check.

Claude Code requires macOS Monterey (12) or later. Earlier versions can have Node.js compatibility issues.

• macOS version check: Open Terminal, run sw_vers, and confirm you are on macOS 12 or higher.
• Terminal access: Use the built-in Terminal at /Applications/Utilities/Terminal or iTerm2 from iterm2.com.
• Anthropic account: You need a Claude.ai Pro/Max subscription ($20/$100/month) or an API account at console.anthropic.com.
• Homebrew requirement: Homebrew is the recommended package manager for macOS. Step 1 covers installation if you do not have it.
• Xcode Command Line Tools: Homebrew requires these. Run xcode-select --install in Terminal if macOS does not prompt you automatically.

If you are not on a Mac, or want the platform-agnostic version of these steps, the complete installation guide covers all platforms.

Step 1: Install Node.js on Mac

Install Node.js using Homebrew. It handles Apple Silicon vs Intel differences automatically and keeps PATH configuration consistent with other developer tools.

Homebrew is the most reliable Node.js path on Mac. It avoids the permission issues and PATH inconsistencies common with the standalone installer.

• Install Homebrew: Run /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" in Terminal. This takes 2-5 minutes.
• Apple Silicon PATH note: On M1/M2/M3 Macs, Homebrew installs to /opt/homebrew/. Run the two PATH commands Homebrew shows at the end of installation.
• Apply PATH changes: Run source ~/.zshrc after adding the PATH lines to load changes in your current session.
• Install Node.js: Run brew install node. This installs the latest LTS version. Node.js 18+ is required.
• Verify installation: Open a new Terminal window and run node --version and npm --version. Both should return version numbers.
• Alternative with nvm: If you switch Node.js versions across projects, install nvm with curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash, then run nvm install --lts.

Open a new Terminal window before verifying. PATH changes do not apply to windows already open when you made the changes.

Step 2: Install Claude Code

Run npm install -g @anthropic-ai/claude-code in Terminal. The installation takes 30-60 seconds and ends with a confirmation showing the installed version.

This installs Claude Code globally so the claude command works from any directory. If claude --version returns a version number, you are done with this step.

• Install command: Run npm install -g @anthropic-ai/claude-code in Terminal and wait for the confirmation line.
• Verify install: Run claude --version. A version number like 1.x.x confirms success.
• Fix "command not found": Run npm config get prefix, then add export PATH="$(npm config get prefix)/bin:$PATH" to ~/.zshrc. Run source ~/.zshrc.
• Fix permissions error: If you see EACCES: permission denied, do not use sudo. Run npm config set prefix ~/.npm-global, add export PATH=~/.npm-global/bin:$PATH to ~/.zshrc, source it, and re-run the install.
• Bash vs Zsh: If you are on Bash rather than Zsh, your config file is ~/.bash_profile. Check your shell with echo $SHELL.

Run source ~/.zshrc after any PATH change, then try claude --version again before troubleshooting further.

Step 3: Authenticate Claude Code on Mac

Navigate to a project directory and run claude. On first launch, Claude Code starts the authentication flow and opens your default browser.

Authentication completes in under a minute. You can use browser OAuth or an API key depending on your setup.

• Navigate to your project: Run cd /path/to/your/project in Terminal before launching Claude Code.
• Browser OAuth: Claude Code opens Safari or your default macOS browser with an Anthropic sign-in page. Sign in and click "Authorise Claude Code CLI."
• Manual URL method: If Safari does not open, Claude Code shows a URL in Terminal. Copy it, paste it into any browser, and the terminal session resumes automatically.
• API key method: Add export ANTHROPIC_API_KEY=your_key_here to ~/.zshrc, run source ~/.zshrc, and Claude Code uses this key on next launch without the browser prompt.
• Team setups: For shared environments or CI/CD, the API key method is the more practical option for managing credentials.

For a complete breakdown of all authentication methods, including team setups and environment configurations, that guide covers every option.

Step 4: Create Your CLAUDE.md File

CLAUDE.md is a Markdown file at your project root that Claude Code reads at the start of every session. It provides persistent context without re-prompting.

Create it in Terminal with touch CLAUDE.md, then open it in your editor with open -a "Visual Studio Code" CLAUDE.md or nano CLAUDE.md.

• Minimal template: Include your tech stack, a brief file structure description, your naming conventions, and your test command (npm test, for example).
• Three lines is enough: Even a tech stack and test command improves Claude Code output noticeably over no CLAUDE.md at all.
• iCloud Drive warning: If your project is in iCloud Drive or Dropbox, sync delays can occasionally cause issues at session start. Keep projects in a local directory like ~/Projects/.
• Conventions section matters: Naming conventions and anti-patterns in CLAUDE.md prevent Claude Code from generating code that violates your project standards.
• Reuse across projects: Save your CLAUDE.md as a template for similar future projects. Starting from a template is faster than building from scratch each time.

A well-written CLAUDE.md is the setup step most developers underinvest in. Spend 20 minutes on it before your first real session.

Common Mac Issues and How to Fix Them

The six most common macOS-specific Claude Code problems are all PATH or environment issues. Each has a one-line fix once you know where to look.

These issues come up frequently on Mac and rarely appear in the general installation guide. Keep this section bookmarked for your team.

• "claude: command not found": npm's global bin is not in your PATH. Fix: add export PATH="$(npm config get prefix)/bin:$PATH" to ~/.zshrc, then run source ~/.zshrc.
• Permissions error on install: Do not use sudo. Configure a user-owned npm prefix directory as described in Step 2.
• Authentication fails in Safari: Set Chrome or Firefox as your default browser in System Settings, then re-run claude. The manual URL method also works.
• Slow first launch on Apple Silicon: Normal behaviour on M-series Macs. First launch takes 5-10 extra seconds due to process initialisation. Not an error.
• Rosetta 2 prompt: Accept it. Some npm packages require Rosetta 2 on M-series Macs. This is a one-time installation and does not affect Claude Code performance.
• Claude Code hangs on a task: Press Ctrl+C to interrupt safely. Review what was written and reissue a more specific instruction.

All six of these are environment issues, not Claude Code issues. The tool is working correctly in each case.

After Setup: What to Do Next

With CLAUDE.md in place and authentication complete, give Claude Code one specific, concrete task: a failing test, a feature from a spec, or a refactor you have been putting off.

Start with a bounded, well-defined task for your first real session. This gives you a clear success condition and a useful reference point for how Claude Code works in your project.

• Run a real task: Go to your project directory, run claude, and describe one specific task with defined inputs and expected output.
• Learn the commands: The full Claude Code command reference covers every slash command, CLI flag, and session configuration option.
• Key keyboard shortcuts: Ctrl+C interrupts a task, Ctrl+D exits the session, /help shows available slash commands from within a session.
• Check your plan tier: If you hit rate limits early, Pro ($20/month) or Max ($100/month) is the next step. For very high volume, direct API access via ANTHROPIC_API_KEY is the most cost-effective option.

The first project walkthrough shows a complete Claude Code session from prompt to commit, which is useful calibration before your first complex task.

Conclusion

Claude Code Mac setup comes down to four steps: Homebrew for Node.js, the right PATH for Apple Silicon, browser OAuth for authentication, and CLAUDE.md for project context.

Most Mac-specific issues are PATH configuration problems with one-line fixes. Run brew install node, then npm install -g @anthropic-ai/claude-code, then claude in your project directory. A working session in under 15 minutes is realistic.

AI App Development

Your Business. Powered by AI

We build AI-driven apps that don’t just solve problems—they transform how people experience your product.

Let's talk

Want Help Getting Claude Code Working Across Your Mac-Based Dev Team?

Most Mac setup friction is not the tool. It is missing PATH configuration, inconsistent shell environments, and no CLAUDE.md template to start from. One developer debugging setup issues for an afternoon costs more than solving it properly upfront.

At LowCode Agency, we are a strategic product team, not a dev shop. We work with Mac-based development teams to configure Claude Code correctly from day one, including CLAUDE.md templates built for your actual stack and team conventions.

• Environment audit: We review your Mac development environment and identify PATH, shell, and Node.js version issues before they become blockers.
• CLAUDE.md template design: We build project-specific CLAUDE.md templates for your common stack types: Node.js, Python, Ruby on Rails, React, and others.
• Team authentication setup: We configure API key management and authentication for teams, including CI/CD environment variables.
• Workflow onboarding: We run your developers through their first real Claude Code sessions on actual client or internal projects.
• Prompt library setup: We document the prompts that produce consistent output for your most common task types across your team.
• Review gate standards: We define the minimum review process for Claude Code output so quality stays consistent as team usage scales.
• Full product team: Strategy, setup, training, and ongoing support from a team that builds with Claude Code every day.

We have built 350+ products for clients including Coca-Cola, American Express, and Medtronic.

If you want Claude Code running reliably across your Mac-based team from day one, talk to our team.