Installing Claude Code the Right Way

Most install guides treat "Claude Code is on my machine" as the finish line. For a working developer it's the starting line — and the install method you pick decides how predictable the next three months are. The mental model worth holding: Claude Code is a single self-updating CLI binary on your PATH, authenticated against your Claude account, that runs from whatever directory you launch it in. Everything downstream — your CLAUDE.md, your Supabase migrations, your Vercel deploys — assumes that binary resolves cleanly in a shell that already knows your project's environment. Get the install boundaries right and the rest of the course is friction-free.

The why: install path is an environment decision

There are three real ways onto your PATH, and they differ in who owns updates.

• The native script (curl ... install.sh on macOS/Linux, irm ... install.ps1 | iex on Windows) drops a self-managing binary. Claude Code updates itself. This is the path you want.
• A package manager (brew install --cask claude-code, winget install Anthropic.ClaudeCode) hands update control to Homebrew or WinGet instead. Fine if you already live there — just don't mix it with the script install, or you'll end up with two binaries and a stale one winning the PATH race.

Node.js is not strictly required to run the CLI, but install the LTS first anyway. Every project on this stack — Next.js App Router, the Supabase JS client, your Vercel build — resolves through Node, and a missing node surfaces as confusing failures inside a Claude session rather than at install time.

The how

# macOS / Linux — verify Node, then install the self-updating binary
node --version            # expect v22.x or similar (LTS)
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell — DON'T elevate; a per-user install belongs in your user profile
node --version
irm https://claude.ai/install.ps1 | iex

Now the step people skip: fully quit and reopen the terminal. The installer edits your shell profile; a live session won't re-read PATH. Then confirm the three invariants:

claude --version    # a version number means the binary resolves
claude login        # opens the browser; sign in with your claude.ai account
claude doctor       # environment self-check — read every line

Treat claude doctor as a real CI gate, not decoration. It reports PATH conflicts, auth state, and Node visibility — exactly the things that bite you two lessons later. Finish by installing VS Code and its official Anthropic extension; the course visuals assume that layout, and the extension shares the same login.

Pitfalls

• command not found: claude — almost always a stale shell, not a failed install. Quit the terminal completely (a new tab is not enough), reopen, retry. A reboot is the nuclear option that always works because it rebuilds PATH.
• Windows execution-policy block — irm | iex dies if scripts are disabled. Fix the scope, not the machine: Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned, confirm, re-run. Don't "fix" it by reopening PowerShell as Administrator — that installs the binary and edits the profile for the wrong user, and the claude you launch normally won't see it. That mismatch is the command not found you'll chase later.
• Two binaries on PATH — the classic outcome of script-installing, then brew-installing later. Run which claude (Get-Command claude on Windows) and keep exactly one.
• Wrong working directory — Claude Code reads files relative to where you launched it. Always cd into the project root first; launching from your home folder gives it the wrong context and over-broad reach.

⌨️ Exercise

Install Claude Code via the native script path for your OS, then prove the environment is sound. In a fresh terminal, capture the output of node --version, claude --version, and claude doctor. If doctor flags anything — a PATH warning, a missing Node, an auth gap — fix it and re-run until every line is clean. Then cd into any real project folder, launch claude, and ask it to print the contents of that directory. Confirm it reads the project's files, not your home folder's — that's your proof the working-directory boundary is correct.