Back to guides

How Do I Set Up Claude Code on macOS Without Breaking My Shell Config?

Jake McCluskey••Beginner•20 min read
How Do I Set Up Claude Code on macOS Without Breaking My Shell Config?

If you just heard about Claude Code and you're about to run a curl script some random blog post handed you, stop. I've watched new developers nuke their zsh setup in five minutes following a "quick install" that wasn't. Here's the walk-through that gets you a working Claude Code in twenty minutes without touching your global shell config, breaking your PATH, or committing you to a payment plan you don't need yet.

Why this matters

Claude Code is Anthropic's official command-line tool for Claude. It lives in your terminal, reads and writes files in your projects, and can actually run shell commands on your behalf. That's powerful — and it's exactly why the setup matters. A messy install puts a global node modules folder in the wrong place, exports half a dozen environment variables into your .zshrc, and leaves you with a fragile setup you'll curse in three months when it breaks after a macOS update.

Done right, the install is four commands, two config decisions, and a working test run.

Before you start

You need:

  • macOS 13 or newer. Older versions technically work, but Node 22 drops support for the oldest macOS builds.
  • A terminal you like. The built-in Terminal is fine. iTerm2 is fine. VS Code's integrated terminal is fine.
  • About 20 minutes and a cup of coffee.
  • An Anthropic account. Free signup at console.anthropic.com. You don't need a paid plan to follow this guide — the Pro subscription and API billing are two different things and I'll explain when each makes sense.

That's it. No Xcode, no Homebrew (yet), no Docker.

Step 1: Install Node the boring way

Claude Code runs on Node.js. You want Node 22 or newer. The single most common Claude Code installation headache comes from installing Node globally with brew install node and then hitting permission errors when the CLI tries to write to /opt/homebrew/lib/node_modules.

Skip that pain. Use nvm (Node Version Manager) — it keeps Node in your home directory and never needs sudo.

bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

After it finishes, close your terminal completely and open a new one. Verify:

bash
command -v nvm

If you see nvm printed back, you're good. If you see nothing, your shell profile didn't get the nvm source line. Open your ~/.zshrc in a text editor and make sure these three lines are at the bottom — nvm adds them automatically, but occasionally iTerm2's profile load order eats them:

bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Now install Node 22 and set it as your default:

bash
nvm install 22
nvm alias default 22

Confirm:

bash
node --version
# v22.x.x

Step 2: Install Claude Code

Now the actual install:

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

Because we used nvm, npm -g installs into ~/.nvm/versions/node/v22.x/bin/ — your home folder, no sudo required. If you ever see a "permission denied" error on this step, it means Node got installed outside nvm. Don't sudo your way through it. Uninstall Node, go back to Step 1, and do it the nvm way.

Confirm the install:

bash
claude --version

You should see a version number. If you see "command not found," your shell hasn't picked up the new path yet — close the terminal and open a new one.

Step 3: Pick your auth — subscription or API

This is the one place people get stuck. Claude Code has two authentication modes and they're billed completely differently.

  • Subscription auth (Claude Pro / Max): $20/mo for Pro, $100/mo for Max. Usage is included in the monthly fee up to generous limits. This is what you want for steady day-to-day work.
  • API auth (pay per token): You get a key from console.anthropic.com and pay for what you use. Every input and output token hits your bill. This is what you want for bursty usage, team deployments, or when you're running Claude from CI.

You can have both configured and switch with a flag. For a first-time setup, pick one:

bash
# If you have Claude Pro or Max:
claude /login

# If you want API billing:
export ANTHROPIC_API_KEY="sk-ant-..."

A critical note on that export: don't put your API key in .zshrc permanently if you share your machine or commit dotfiles to GitHub. Use a secrets manager, or a per-project .envrc with direnv, or just unset it when you're done.

Step 4: Write your first CLAUDE.md

Claude Code reads a file called CLAUDE.md at the root of your project and treats it as persistent context for every session. This is the single biggest lever for making Claude useful. No CLAUDE.md and you're re-explaining your project every conversation. A good CLAUDE.md and Claude lands contributing on day one.

Go to any project folder:

bash
cd ~/code/my-project

Create the file:

bash
claude init

That drops a starter CLAUDE.md at the project root. Open it and replace the boilerplate with three things:

  1. What this project is. One sentence. "Elite AI Advantage is a Next.js marketing site with a Postgres backend running on Railway."
  2. The conventions. "We use TypeScript strict mode. Tailwind for styling. Prisma for the database. Never edit generated files in /node_modules or .next."
  3. The workflow. "Run npm run build before committing. Run npm run lint when a PR is up. Never push to main — open a PR."

Keep it under 200 lines. If it gets longer, split it into .claude/rules/*.md files — Claude Code auto-loads everything in that directory. A 400-line wall of text falls off the context window; a structured set of short rule files doesn't.

Step 5: Run a real task

From the same project folder:

bash
claude

You drop into the Claude Code interactive prompt. Try something concrete:

text
List the top-level files and tell me what each one does.

Claude should run ls, read a handful of files, and give you a short summary. If it does, your install is working.

Verify it worked

A clean install passes three checks:

bash
# 1. Node is local to your home directory
which node
# expected: ~/.nvm/versions/node/v22.x/bin/node

# 2. Claude is installed and executable
claude --version
# expected: a version number

# 3. Claude can read and write in your project
cd ~/code/any-project
claude

If all three pass, you're set. Next time your shell opens, nothing broken, nothing global in /usr/local, nothing requiring sudo.

Where this breaks

A few traps that cost me time so you don't have to:

  • Using Homebrew's Node alongside nvm. Don't. Pick one. If you already have brew install node in your setup, run brew uninstall node before running nvm install 22. Otherwise command -v node returns whichever was first in your PATH and you'll have random "wrong Node version" bugs forever.
  • Symlinking Claude Code into /usr/local/bin. Tempting because it makes it available to cron and launchd. Don't. When nvm upgrades Node, the symlink goes stale and every cron job silently fails. Reference the full path or use a wrapper script.
  • Putting ANTHROPIC_API_KEY in a committed dotfile. If you back up your dotfiles to GitHub, even a private repo, you're one leak away from a stolen key. Use direnv or 1Password CLI.
  • Running claude in your home directory. It defaults to thinking your whole home is the project. It'll read your .ssh/config if you let it. Always cd into a project folder first.
  • The "shell integration" prompt. On first launch Claude Code offers to add shell integration to your .zshrc. It writes a handful of aliases and completion scripts. I usually decline — it works fine without them, and if you ever switch shells you don't have to remember to remove anything.

What to try next

Want this built for you instead?

Let's talk about your AI + SEO stack

If you'd rather skip the how-to and have it shipped for you, that's what I do. Start a conversation and we'll figure out the fastest path to results.

Let's Talk
Questions from readers

Frequently asked

Do I need Homebrew?

No. I skip Homebrew for Node installs because it tends to collide with nvm and creates permission errors that don't show up until you hit your first global npm install. Use nvm and Node 22, as laid out in Step 1.

Pro subscription or API key — which should I start with?

Subscription if you're doing steady daily work. API if you're bursty or automating from CI. You can have both configured on the same machine and switch with a flag, so it's not a forever decision.

Can I use this on Linux?

Almost all of it, yes. The nvm step works the same. The shell-integration detail assumes zsh, which is the macOS default; on Linux you're probably on bash or fish, so adjust those file names accordingly.

Does Claude Code ever ask before running dangerous commands?

Yes — out of the box it prompts before Bash, Edit, and Write operations. You can loosen that with permissions config once you're comfortable, but keep the prompts on while you learn what Claude does in your project.

What goes in CLAUDE.md versus .claude/rules/*.md — and when should I split?

Keep CLAUDE.md as your one-page overview: what the project is, the main conventions, the workflow. When it crosses roughly 200 lines, move specifics into focused rule files like .claude/rules/testing.md or .claude/rules/styles.md. Claude Code auto-loads everything in that directory.