Claude Code Windows: installation, Git Bash, WSL and rakes along the way

What does this solve?

Claude Code Windows is the most common request from those who have a work machine that is not on macOS: the official instructions are written based on the Unix shell, and discrepancies begin at the very first step. The package is installed claude starts, and then the agent tries to execute ls -la, stumbles upon the absence of bash, gets confused in paths with backslashes and in PowerShell quotes. A separate portion of the rake awaits those who put everything inside WSL: it has its own problems with the Node version, with disk performance /mnt/c and with line breaks, which after the first edit turn the diff into a completely rewritten file. Below are both working circuits and a list of breakdowns that occur in almost everyone.

How it works

On Windows there are two independent launch methods, and it is better to choose between them once, rather than mix them.

Circuit 1: native Windows. CLI is installed on Windows, works with NTFS files directly, PowerShell remains the main terminal. The key detail is that the command launch tool is designed for the POSIX shell, so the native installation needs Git for Windows: agent commands go to bash.exe from his kit. If Git is not installed or is not where expected, the path is set by an environment variable CLAUDE_CODE_GIT_BASH_PATH.

Circuit 2: WSL2. Node and CLI are installed inside the distribution, then everything behaves like regular Linux - without reservations about the shell, paths and rights. Board - separate file systems: a project located in /mnt/c/Users/..., is read and written through an interlayer and works noticeably slower, especially on directories like node_modules with tens of thousands of small files.

Where the settings live. User directory - %USERPROFILE%\.claude (in WSL - ~/.claude), project settings - .claude\settings.json and personal .claude\settings.local.json next to the code, project memory - CLAUDE.md at the root of the repository. Permission rules are written with forward slashes (Read(./src/**)) regardless of what the paths look like in Explorer.

What breaks at the junction. PATH after global npm installation, PowerShell script execution policy for .ps1wrappers, path length limit of 260 characters, Cyrillic in the username, antivirus that scans every file in node_modules, and a corporate proxy with TLS certificate spoofing.

One line rule: if the project has a Makefile, bash scripts or docker-compose - install in WSL; if the stack is purely Windows (.NET, PowerShell, MSBuild) - install it natively, but be sure to use Git for Windows.

How to connect

Native installation

Step 1. Terminal and Node. Windows Terminal with PowerShell - working minimum; classic cmd.exe copes worse with colors and transfers. Node.js is installed with the current LTS version (the required minimum is indicated on the installation page).

node --version
npm --version

Step 2. Package.

npm install -g @anthropic-ai/claude-code
where.exe claude
claude --version

If where.exe claude does not find anything, the global packages directory is not in PATH. Look like this:

npm config get prefix

The resulting path (usually inside %APPDATA%\npm) is added to the user's PATH variable, after which the terminal is restarted - the open session does not re-read the old PATH.

Step 3. Error about prohibiting script execution. If start claude crashes with a message about the execution policy, this can be removed at the level of the current user, without administrator rights:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Step 4. Git for Windows. Installed from the official website. If the agent complains that it cannot execute a shell command, the path to bash is specified explicitly:

setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"

Variable is read when the process starts - terminal after setx is restarted.

Step 5. First launch.

cd C:\projects\my-app
claude

Inside: /login, then /status (account, model, working directory) and /init for starter CLAUDE.md.

Installation in WSL2

Step 1. Distribution. wsl --install from PowerShell with administrator rights, reboot, create user.

Step 2. Node inside the distribution. The most common mistake is to use Node installed on Windows: it is visible from WSL via PATH and works externally. Check:

which node && which npm

Paths must start with /usr or /home, not with /mnt/c. If they start with /mnt/c, Node is installed inside the distribution (via a package manager or version manager), and Windows paths are removed from the beginning of PATH.

Step 3. Package.

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

If npm refuses to install a package, citing a platform mismatch (a consequence of a mixed installation), it helps to explicitly specify the platform in the npm config before trying again.

Step 4. Where to keep the project. In Linux file system - ~/projects/..., not in /mnt/c/Users/.... You can open such a project from the Windows editor through the remote connection mode to WSL, but putting the sources on the C drive and working with them from WSL is a sure way to get a slow build and missed file watcher events.

Repository hygiene (both circuits)

Line breaks - a source of diffs where “the entire file has been changed”:

git config --global core.autocrlf input

and file .gitattributes in the repository:

* text=auto eol=lf

Long paths are enabled at the Git and system level:

git config --global core.longpaths true

The antivirus sets exceptions for the project directory and npm cache - otherwise, every step of the agent is limited to checking files. For a corporate proxy with certificate substitution, you will need variables HTTPS_PROXY i NODE_EXTRA_CA_CERTS with the path to the company's root certificate.

Useful scripts

Window stack without bash wrapping (.NET, MSBuild, PowerShell scripts) - native installation plus Git for Windows for the sake of the shell.
Web project with docker-compose and shell scripts - WSL2, project in the Linux home directory.
Parsing a crashed assembly: the command output is put into context via ! directly from the session, without copy-pasting from another window.
One-time task on someone else’s machine without administrator rights: installation with an npm package in the user’s profile, without an installer.
Working with two repositories at once - --add-dir to a second directory instead of running from a common parent.
Automatic check before pushing: claude -p with a diff on the input, called from a Git hook, which in a Windows repository is still executed by Git bash.

Limitations

The command launcher is waiting for a POSIX shell. Without Git for Windows, the native installation remains semi-working: files can be read and edited, but running commands fails.
Mixed installation is not well supported: Node from Windows plus CLI inside WSL gives floating errors that are not diagnosed by the message.
Project on /mnt/c is slow when working from WSL, and this cannot be cured by settings - only by transferring it to the Linux file system.
Cyrillic and spaces in the username break part of the toolchain before the CLI itself; in a controversial case, it is easier to create a profile with a Latin name than to repair each package separately.
The path length limit is not limited only to Git: builders and package managers create deep subdirectories, and without long paths enabled, it is the installation of dependencies that fails.
The key combinations do not completely coincide with the terminal ones: line breaks in multi-line input and inserting an image from the buffer depend on the terminal, some are configured via /terminal-setup.
Hooks and permission rules written for Unix utilities work on a native installation only as long as Git bash is nearby; in the team repository this should be written to CLAUDE.md.

How to check the result

claude doctor —shows installation type, version and environment problems; This is the first command for any “does not start”.
where.exe claude (or which claude in WSL) - there is exactly one path; two executable files found mean that a native installation and an installation from WSL are running in parallel.
/status in session - the working directory is the same as the project, not the user's home directory.
Shell check: ask agent to perform pwd && ls -la. Response with directory contents - Git bash found; startup error - check CLAUDE_CODE_GIT_BASH_PATH.
Checking line breaks: ask to change one line in an existing file and see git diff. The diff should contain one line, not the entire file.
Checking WSL installation: which node returns the path inside Linux, pwd in the project directory does not start with /mnt/c.
Network and proxy check: if authorization or update fails due to timeout, npm ping from the same terminal will show whether the problem is in the CLI or in the corporate proxy.
Check run: claude -p "Выведи имя текущей ветки и число незакоммиченных файлов" is a short task that is enough to simultaneously check the shell, rights and access to the repository.