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.shon macOS/Linux/WSL,irm ... install.ps1 | iexin 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 runbrew upgrade claude-codeorwinget upgrade Anthropic.ClaudeCodeyourself, or opt in by setting the environment variableCLAUDE_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 thePATHrace. - 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.
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 rebuildsPATH.- Windows execution-policy block:
irm | iexdies 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 theclaudeyou launch normally won't see it. That mismatch is thecommand not foundyou'll chase later. - Two binaries on
PATH: the classic outcome of native-installing, thenbrew-installing later. Runwhich -a claude(Get-Command claude -Allon Windows) and keep exactly one.claude doctorflags this too. - Wrong working directory: Claude Code reads files relative to where you launched it. Always
cdinto 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.
look at my project
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.
- 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.denyrule for.envfiles (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.
- 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 --versionandclaude doctor. - Launch from the project root, and make the first prompt read-only and secret-safe.

