Install Claude Code Before Your First Real Repo Task

The easiest way to misread Claude Code is to let setup sprawl into a tooling experiment.

On day one, three different decisions often get mixed together:

• which install channel you are using
• which account type you are logging in with
• whether Windows should be treated as native Git Bash or as a WSL workflow

When those get blurred, every failure looks like the product is unstable.

A PATH issue looks like Claude is broken. An expired Console or API setup looks like login is broken. Choosing the wrong shell surface makes a repo task feel clumsy even when the model is fine.

This page is about preventing that.

Start With The Current Default, Not With Old npm Advice#

If you search around, you will still find third-party guides that start with the older npm package. That is no longer the cleanest first path.

Anthropic's current setup docs recommend the native installer first, with Homebrew and WinGet as supported alternatives. That matters because the update story is different depending on how you installed Claude:

• native install auto-updates in the background
• Homebrew and WinGet need manual upgrades
• older npm-first advice now creates more confusion than value for a fresh setup

If you are starting from zero, use the native installer unless your team already standardizes on Homebrew or WinGet.

macOS, Linux, Or WSL#

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

Windows PowerShell#

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

Windows CMD#

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

If you are on macOS and already use Homebrew for developer tools, this is a reasonable second choice:

brew install --cask claude-code
claude --version

If you are on Windows and your team prefers WinGet-managed tools:

winget install Anthropic.ClaudeCode
claude --version

The wrong move is mixing those channels casually. If you install Claude natively and then later layer WinGet or an old npm package on top, you stop knowing which binary your shell is actually launching.

Click to enlarge

Official Claude Code product screenshot checked on 2026-04-16. The useful detail here is the native install command on the current public Claude Code surface, not the surrounding marketing copy.

Pick The Account Lane Before You Even Open A Repo#

Claude Code does not sit on the free Claude.ai plan. The current docs say you need one of these:

• Claude Pro or Max
• Claude for Teams or Enterprise
• Claude Console
• a supported cloud provider path such as Bedrock, Vertex, or Foundry

That list matters because "I can open claude.ai in my browser" does not automatically mean "this machine is ready for Claude Code."

For an individual developer testing the CLI on a real repository, the cleanest first lane is usually a Claude subscription login. Run claude, let it open the browser flow, and complete OAuth.

If your team wants API-style billing instead of subscription access, use the Console path on purpose:

claude auth login --console
claude auth status --text

Use Console or cloud-provider auth when that billing model is already the real target. Do not choose it on day one just because it sounds more technical.

On Windows, The Real Choice Is Native Git Bash Or WSL#

Windows setup is where people still waste the most time because old advice and current advice are not aligned.

The current Claude docs support two real paths:

• native Windows, which still relies on Git for Windows and Git Bash
• WSL, for teams whose actual toolchain and repos already live there

The key point is that WSL is no longer the default answer for every Windows developer.

Use native Windows when:

• your editor, repo, and package managers already live on Windows
• you want the shortest route to testing Claude Code
• you do not need a Linux-only toolchain for the first task

Use WSL when:

• the repo already lives under Linux
• your build or runtime assumptions are Linux-shaped
• the team already debugs and runs commands inside WSL

Do not split the difference. The worst first-run setup is a repo half on Windows, half in WSL, with Git, package managers, and Claude all resolving from different places.

Native Windows Still Needs Git For Windows#

Claude Code on native Windows needs Git for Windows. If Git is missing, Claude will complain that Windows requires git-bash.

Install Git for Windows first, make sure it is on PATH, then launch Claude again. If Git is installed but Claude still cannot find Git Bash, set the path explicitly in settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

If you are not sure which git Windows is using, check before you keep retrying:

where.exe git
Get-Command claude | Select-Object Source

That second line is worth doing when claude behaves strangely on Windows. Anthropic's troubleshooting docs note that older Claude Desktop installs can register a Claude.exe in WindowsApps and steal PATH priority from the CLI.

WSL Is Fine, But Treat It As A Full WSL Workflow#

If your project genuinely belongs in WSL, stay there fully:

• install Claude inside WSL
• keep the repository inside the Linux filesystem, not under /mnt/c/...
• do browser login with a working Windows browser handoff, or copy the URL manually

One WSL-specific login trap is easy to miss: the browser handoff can fail even when Claude itself is fine. If WSL cannot open your Windows browser, set BROWSER first:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

If that still fails, press c when Claude shows the login URL and paste it into the browser yourself.

Verify The Setup Before You Hand It A Real Repository#

Do not make your first real bug fix the thing that also verifies installation.

A clean setup check is boring on purpose:

claude --version
claude doctor
claude auth status --text

Those three checks tell you different things:

• claude --version proves your shell can resolve the binary you intended to install
• claude doctor checks installation and configuration health
• claude auth status --text tells you whether this machine is actually logged in

If those checks are already unstable, the repo trial will not teach you anything trustworthy.

If they fail in a confusing way, go straight to Debug a Claude Code Run With Logs, File Scope, and a Tighter Follow-Up Prompt. The first debug step there is not "write a better prompt." It is to classify whether the machine, the permissions, or the task boundary is actually broken.

The Most Common Login Trap Is Not Browser Login#

The browser flow is not usually the real problem. The more common trap is auth precedence.

Anthropic's current auth docs say Claude chooses credentials in a specific order. If ANTHROPIC_API_KEY is present and approved, that key takes precedence over your subscription login. That means a stale API key can quietly override a perfectly valid Pro, Max, Team, or Enterprise subscription.

This is exactly the kind of problem that makes developers say "Claude keeps asking me to log in" when the real issue is credential precedence.

If you expected subscription auth but suspect an old API key is taking over:

unset ANTHROPIC_API_KEY
claude

Then confirm the active auth path with /status inside Claude Code.

For Windows PowerShell, the same principle applies even if the command differs. The important part is not the shell syntax. The important part is removing the old variable before you keep diagnosing OAuth.

Native Install And Update Behavior Are Different From Brew Or WinGet#

This is another place where old mental models cause needless confusion.

With the native installer, Claude checks for updates on startup and applies them in the background. With Homebrew and WinGet, you still need to upgrade manually.

That means your update habit should match your install channel:

• native install: let auto-update handle most of it, or use claude update when needed
• Homebrew: brew upgrade claude-code or brew upgrade claude-code@latest
• WinGet: winget upgrade Anthropic.ClaudeCode

If your shell reports one version but you expected another, stop and verify the install channel before assuming the product changed behavior.

If You Used The Old npm Package Before, Do One Clean Cutover#

Some older tutorials and videos still point people to the npm package. That advice is not always malicious. It is just old.

If you previously used the npm route, the practical fix is not to keep two working installations forever. The fix is to make one deliberate cutover:

1. decide which channel you want to keep
2. verify which claude binary your shell resolves
3. remove or stop updating the old path
4. rerun claude --version, claude doctor, and claude auth status --text

The first real repo task should not also be a binary archaeology exercise.

Leave Setup Only After These Five Checks Pass#

Before you judge Claude Code on a real repository, make sure all five are true:

1. claude launches from the shell you actually use for work
2. you deliberately chose native Windows or WSL instead of drifting between them
3. you know whether this machine is using subscription, Console, or cloud-provider auth
4. claude doctor and claude auth status --text look healthy
5. you are not carrying a stale ANTHROPIC_API_KEY that overrides the auth method you thought you were testing

Once those are true, the next tutorial finally becomes honest. You are no longer testing install drift. You are testing whether Claude Code actually helps on a real repo task.

Official References#

• Advanced setup
• Authentication
• CLI reference
• Commands
• Troubleshooting
• Permission modes

What To Read Next#

Read Use Claude Code on One Real Repo Task Without Letting the Shell Loop Drift once installation, auth, and Windows surface are settled.

Read Setup Playwright MCP With Claude Code if your actual next step depends on browser automation rather than a plain repo task.

Read Cursor vs Claude Code if the real question is terminal control versus editor-native flow.