Skip to main content
← Back to course

DEV-102-1.1

Installing Claude Code the Right Way

Verified current as of November 14, 2026

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.

You need a paid Claude plan (Pro, Max, Team, or Enterprise) or an Anthropic Console account for API billing. Claude Code isn't on the Free plan, as of November 2026.

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 installer (curl ... install.sh on macOS/Linux/WSL, irm ... install.ps1 | iex in Windows PowerShell) drops a self-managing binary that updates itself in the background. 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. Those installs don't auto-update by default: you run brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode yourself, or opt in by setting the environment variable CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1, which has Claude Code run that upgrade in the background (on WinGet it can fail while Claude Code is running, because Windows locks the executable). Fine if you already live there; just don't mix it with the native install, or you'll end up with two binaries and a stale one winning the PATH race.
  • npm (npm install -g @anthropic-ai/claude-code) still exists for environments that need it and requires Node.js 22 or later. Prefer the native installer on a dev box.

The native binary doesn't need Node.js. Install the Node LTS 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.

On native Windows, install Git for Windows too. With it, Claude Code uses Git Bash for its Bash tool; without it, Claude Code runs shell commands through PowerShell instead. Either works, but your teammates' instructions and scripts will mostly assume Bash.

The how

# macOS / Linux / WSL: verify Node, then install the self-updating binary
node --version            # expect an LTS release, e.g. v22.x or later
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 doctor       # read-only install + settings diagnostics; read every line
claude              # first launch prompts you to sign in (or run: claude auth login)

Treat claude doctor as a real gate, not decoration. It reports install health, a second launcher on PATH, settings-file validation errors, and the result of the last auto-update attempt: exactly the things that bite you two lessons later. Finish by installing VS Code and the official Claude Code extension from Anthropic; it shares the same sign-in.

A left-to-right flow showing the Claude Code setup sequence: verify Node, install the self-updating binary, restart the terminal, run the verification commands, then install the VS Code extension.

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. The installer doesn't need it, and an elevated run installs the binary and edits the profile for the wrong user, so 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 native-installing, then brew-installing later. Run which -a claude (Get-Command claude -All on Windows) and keep exactly one. claude doctor flags this too.
  • 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.

The engineered first prompt

Your first prompt in a new repo should make Claude prove it's pointed at the right place and learn the project before it touches anything.

Vague prompt — what most people type
look at my project
Engineered prompt
You're in a Next.js App Router + Supabase repo. Don't edit anything yet.

1. Print the absolute path you're working in and list the top-level folders.
2. Read package.json and tell me the exact commands for dev, build, lint, typecheck, and test. If one is missing, say so; don't invent it.
3. Tell me which Node version the project expects (engines field, .nvmrc, or .node-version) and whether it matches `node --version` here.
4. List any file that looks like it holds secrets (.env*, *.pem, service-account JSON) by NAME ONLY. Do not open or print their contents.

Finish with a three-line summary I can paste into CLAUDE.md.

What each element changes: "Don't edit anything yet" keeps the first turn read-only even if your permission mode would allow edits. The absolute path proves the working-directory boundary. "Don't invent it" stops plausible-but-wrong commands. "By NAME ONLY" keeps secret values out of the transcript.

Current limitations· as of November 2026
  • Paid plan or Console account required. Claude Code isn't included on the Free plan, as of November 2026.
  • Package-manager installs lag. Homebrew and WinGet installs don't auto-update by default (opt in with CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1); native installs do.
  • The default permission mode varies by version and plan. Recent versions start in Auto mode in the terminal and VS Code; check the status line before you trust that a first prompt is read-only, or start with claude --permission-mode plan.
  • "By name only" is an instruction, not a control. Pair it with a permissions.deny rule for .env files (covered in the Hooks lesson).

⌨️ Exercise

Install Claude Code via the native installer 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 second launcher, a settings error) fix it and re-run until every line is clean. Then cd into any real project folder, launch claude --permission-mode plan, and send the engineered prompt above. Confirm it reads the project's files, not your home folder's: that's your proof the working-directory boundary is correct.

Key takeaways
  • Use the native installer: it self-updates; Homebrew and WinGet installs don't by default unless you set CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1.
  • Never elevate the Windows install; scope the execution policy to CurrentUser instead.
  • Restart the terminal, then verify with claude --version and claude doctor.
  • Launch from the project root, and make the first prompt read-only and secret-safe.