TheDefinitiveGuidetoSettingUpClaudeCodeonWindowsandmacOS

I have been using Claude Code every day for over a year to build infrastructure, write Terraform, debug Kubernetes manifests, and ship production code faster than I ever thought possible. This is the guide I wish existed when I started -- not the sanitized official docs, but the real-world walkthrough that covers every gotcha, every platform quirk, and every trick I have learned the hard way.

By the end of this guide, you will have Claude Code installed, authenticated, configured for your workflow, integrated into your editor, and running your first real session. Whether you are on a Mac or Windows, a beginner or a senior engineer, this guide has you covered.

Who Is This For?

• First-time users who have never touched Claude Code
• Engineers switching from GitHub Copilot or other AI coding tools
• Windows users who have been told "just use a Mac" one too many times
• Team leads evaluating Claude Code for their organization
• Anyone who tried the official quickstart and got stuck

What Is Claude Code, Actually?

Claude Code is not a chatbot with a code plugin. It is a full AI coding agent that lives in your terminal. It can:

• Read your entire codebase automatically -- no manual context loading
• Write, edit, and create files across your project
• Run shell commands (build, test, deploy) with your permission
• Use Git conversationally -- commits, branches, PRs, conflict resolution
• Debug errors by reading stack traces and tracing through your code
• Refactor at scale -- rename across files, extract modules, restructure directories

It understands context. Ask it "why is the build failing?" and it will read your error output, trace the source, and fix it. That is fundamentally different from autocomplete.

Step 0: Choose Your Plan

Before installing anything, you need an account. Here is the honest breakdown:

My recommendation: Start with Pro at $20/month. It gives you full Claude Code access plus Claude on the web and the desktop app. If you hit rate limits frequently, upgrade to Max. If you only need Claude Code in CI/CD pipelines, Console with API credits is more cost-effective.

How to Sign Up

1. Go to claude.ai and click Sign Up
2. Create your account with email, Google, or Apple SSO
3. Navigate to claude.ai/pricing and select your plan
4. Enter payment details and confirm
5. Your account is ready -- proceed to installation

Step 1: Install Claude Code on macOS

macOS is the smoothest experience. Three options, ranked by what I recommend:

Option A: Native Installer (My Pick)

Open Terminal (or iTerm2, Warp, whatever you use) and run:

curl -fsSL https://claude.ai/install.sh | bash

Why this is best: Auto-updates silently in the background. You will always be on the latest version with zero maintenance. No package manager dependency.

After it finishes, verify:

claude --version

You should see something like Claude Code v1.x.x. If you see "command not found," close and reopen your terminal -- the PATH update needs a fresh shell.

Option B: Homebrew

If you manage everything through Homebrew:

brew install --cask claude-code

The catch: Homebrew installs do NOT auto-update. You need to run brew upgrade claude-code manually. I have seen people run months-old versions without realizing it. Set a calendar reminder or just use the native installer.

Option C: WinGet (If You Are on macOS via Parallels)

This is technically a Windows option, but if you run Windows in Parallels on your Mac:

winget install Anthropic.ClaudeCode

macOS Gotchas Nobody Tells You

• Gatekeeper warning: The first time you run claude, macOS might show a security dialog. Click "Allow" or go to System Settings > Privacy & Security and approve it.
• Shell matters: Claude Code works best with Zsh (the default on macOS) or Bash. If you use Fish, it works but some interactive features may behave differently.
• PATH issues with Homebrew: If claude is not found after a Homebrew install, run brew link claude-code or add the Homebrew bin to your PATH manually.
• Apple Silicon vs Intel: The native installer automatically detects your architecture. No action needed.

Step 2: Install Claude Code on Windows

Windows support has come a long way. Here are your options, ranked:

Option A: PowerShell Native Installer (Recommended)

Open PowerShell as Administrator (right-click > Run as Administrator):

irm https://claude.ai/install.ps1 | iex

This installs Claude Code natively on Windows. Like the macOS version, it auto-updates.

Verify:

claude --version

Option B: Windows Command Prompt

If you prefer CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Option C: WinGet

For Windows Package Manager users:

winget install Anthropic.ClaudeCode

Same caveat as Homebrew -- no auto-updates. Run winget upgrade Anthropic.ClaudeCode periodically.

Option D: WSL (My Pick for Serious Development)

If you are doing real development on Windows, you should be using WSL. This gives you a full Linux environment where Claude Code feels native:

# Install WSL with Ubuntu (run in PowerShell as Admin)
wsl --install -d Ubuntu

Restart your computer, then open Ubuntu from the Start menu:

# Inside your WSL Ubuntu terminal
curl -fsSL https://claude.ai/install.sh | bash
claude --version

Why WSL is superior for Claude Code: Bash tool sandboxing works properly (it does not on native Windows). File system performance is better when working inside the WSL filesystem (/home/user/projects not /mnt/c/Users/...). And your Claude Code setup matches what you would have on macOS or Linux, so all documentation and tutorials apply directly.

Option E: Git Bash

If you already have Git for Windows installed:

# Open Git Bash
curl -fsSL https://claude.ai/install.sh | bash

Windows Gotchas Nobody Tells You

• Antivirus interference: Windows Defender or corporate antivirus may flag the installer. Add an exception for %USERPROFILE%\.local\bin\claude.exe if you see blocked warnings.
• PowerShell execution policy: If irm | iex fails with a policy error, run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser first, then retry.
• Path length limits: Windows has a 260-character path limit by default. If your project has deeply nested node_modules, enable long paths: reg add HKLM\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1 /f
• Line endings: Claude Code respects your Git config for line endings. Make sure git config --global core.autocrlf input is set to avoid CRLF issues.
• Native Windows requires Git Bash: The native Windows installer needs Git for Windows to be installed. If you do not have it, install Git first.

Step 3: Authenticate

This only happens once. Your credentials are stored securely after the first login.

cd ~/your-project
claude

Claude Code launches and shows an authentication prompt. It opens your default browser where you log in with your Claude account. Once authenticated, you are returned to the terminal with a welcome screen.

What you will see:

Welcome to Claude Code!

Session: new session
Model: claude-sonnet-4-20250514

Type /help for available commands
>

If you need to switch accounts later, type /login inside Claude Code.

Authentication Options

• Claude Pro/Max/Teams/Enterprise (recommended): Log in with your claude.ai account. Simplest option.
• Claude Console: For API-based access. A dedicated "Claude Code" workspace is automatically created for cost tracking.
• Cloud Providers: Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. Best for enterprises with existing cloud contracts.

Step 4: Run the Health Check

Before doing anything else, run the built-in diagnostic:

claude doctor

This checks your environment for common issues: PATH configuration, shell compatibility, network connectivity, and version status. Fix anything it flags before proceeding.

Step 5: Your First Real Session

Forget "hello world." Let us do something actually useful.

Understand a New Codebase

Navigate to any project and start Claude Code:

cd ~/projects/my-app
claude

Then type:

give me a high-level architecture overview of this project. what are the main components, how do they connect, and where are the entry points?

Claude reads your file tree, examines key files, and gives you a structured summary. This alone is worth the subscription -- it turns hours of code archaeology into 30 seconds.

Fix a Real Bug

the build is failing with "Module not found: Can't resolve './utils/helpers'"
-- find the broken import and fix it

Claude will trace the import chain, find the mismatch, and propose the fix. You approve it, and it is done.

Write Tests

write comprehensive unit tests for src/lib/auth.ts using the existing test patterns in this project

Claude examines your test directory, matches the style and framework you are already using, and generates tests that actually pass.

Step 6: Set Up CLAUDE.md (The Secret Weapon)

This is the single most impactful thing you can do to make Claude Code work better, and most people skip it.

Create a CLAUDE.md file in your project root:

touch CLAUDE.md

Then add your project conventions:

# Project Context

## Tech Stack
- Next.js 14 with App Router
- TypeScript strict mode
- Tailwind CSS
- PostgreSQL with Prisma ORM

## Coding Conventions
- Use functional components with hooks (no class components)
- Prefer named exports over default exports
- All API routes go in src/app/api/
- Use Zod for runtime validation on all API inputs
- Error messages should be user-friendly, not technical

## Testing
- Jest for unit tests, Playwright for E2E
- Test files go next to the source file: Component.tsx -> Component.test.tsx
- Minimum 80% coverage on new code

## Git Conventions
- Commit messages follow Conventional Commits (feat:, fix:, chore:)
- Branch names: feature/description, bugfix/description
- Always rebase, never merge

## Important Notes
- Never commit .env files
- The database migration must be backward-compatible
- All user-facing strings must support i18n

Claude reads this file automatically at the start of every session. It is like giving your AI pair programmer a one-page onboarding document. The difference in output quality is dramatic.

Step 7: Integrate with Your Editor

Claude Code is not limited to the terminal. Set it up in your editor for the best experience.

VS Code

1. Open VS Code
2. Go to Extensions (Cmd+Shift+X / Ctrl+Shift+X)
3. Search for "Claude Code"
4. Install the official Anthropic extension
5. Open the Claude Code panel from the sidebar

JetBrains (IntelliJ, PyCharm, WebStorm)

1. Open Settings > Plugins
2. Search for "Claude Code"
3. Install and restart your IDE
4. Access Claude Code from the tool window

Cursor

If you use Cursor (like I do), Claude Code works as a standalone terminal tool alongside Cursor's built-in AI. Run claude in Cursor's integrated terminal for the best of both worlds.

Essential Commands Cheat Sheet

Power User Tips

Use slash commands for speed. Type / inside Claude Code to see all available commands and skills.

Pipe output into Claude. You can feed command output directly:

npm test 2>&1 | claude "analyze these test failures and fix the root causes"

Use the stable release channel for production workflows. In your settings, set autoUpdatesChannel to stable to avoid bleeding-edge regressions:

claude
# Then inside Claude Code:
/config
# Select "Auto-update channel" > "stable"

Create project-specific skills. Drop markdown files in .claude/skills/ to teach Claude domain-specific knowledge that persists across sessions.

Multi-file operations. Claude Code excels at cross-file refactoring. Instead of editing one file at a time, describe the full change:

rename the UserService class to AuthenticationService across the entire codebase,
update all imports, and update the dependency injection configuration

Troubleshooting

"command not found: claude"

Close and reopen your terminal. If that does not work:

# macOS/Linux -- check where it installed
ls ~/.local/bin/claude

# Add to PATH manually if needed
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

On Windows:

# Check if installed
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

# Restart your terminal or open a new one

Authentication Fails

• Make sure you have an active paid subscription. Free accounts do not include Claude Code.
• If the browser redirect fails, try logging in at claude.ai first, then retry claude in your terminal.
• Corporate firewalls may block the OAuth redirect. Ask your IT team to allow claude.ai and anthropic.com domains.

Slow Responses

• Check your internet connection -- Claude Code streams responses from Anthropic's servers
• If you are on a VPN, try disconnecting temporarily
• Large files (10,000+ lines) take longer to process. Break them up or point Claude to specific functions

Permission Errors on macOS

chmod +x ~/.local/bin/claude

Windows Defender Blocking

Add an exclusion in Windows Security > Virus & Threat Protection > Manage Settings > Exclusions for %USERPROFILE%\.local\bin\

Nuclear Reset (When All Else Fails)

# Remove Claude Code completely
rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude
rm -rf ~/.claude
rm -f ~/.claude.json

# Reinstall
curl -fsSL https://claude.ai/install.sh | bash
claude --version

Uninstalling Claude Code

If you ever need to remove it:

macOS/Linux:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

Windows PowerShell:

Remove-Item -Path "$env:USERPROFILE\.local\bin\claude.exe" -Force
Remove-Item -Path "$env:USERPROFILE\.local\share\claude" -Recurse -Force

Homebrew: brew uninstall --cask claude-code

WinGet: winget uninstall Anthropic.ClaudeCode

To also remove all settings and history, delete ~/.claude and ~/.claude.json.

What Makes This Different from the Official Docs

The official Anthropic documentation is accurate but clinical. It tells you the commands. This guide tells you what actually happens, what goes wrong, and what to do about it. It is written by someone who uses Claude Code 8+ hours a day to build real infrastructure and ship real code.

If you found this useful, check out my other posts on AI-powered cloud engineering and building self-healing infrastructure with Claude Code.

Have questions about setting up Claude Code? Reach out on LinkedIn or GitHub.