Claude Code on Windows: the complete setup and troubleshooting guide

Short answer: Claude Code runs on Windows both natively — from PowerShell or Git Bash — and inside WSL2. The setup is straightforward, but a handful of Windows-specific details trip people up: where config and transcripts live, how CRLF line endings collide with LF-default tooling, and how path quoting differs between shells. This guide is the hub for running Claude Code well on Windows, and it links out to focused pages for Claude Code WSL2 setup, usage limits, and what Claude Code costs.

Native Windows vs WSL2: which to run

You have two good paths on a Windows machine.

Native Windows runs Claude Code directly against your Windows filesystem. It’s the simplest to start with, works from PowerShell or Git Bash, and keeps your files on the familiar C: drive. This is the right default if your projects already live on Windows and your toolchain is Windows-native.

WSL2 gives you a real Linux environment alongside Windows. If your project expects a Unix shell, Linux build tools, or containerized workflows, running Claude Code inside the distro avoids a whole class of cross-platform friction. The trade-off is that files and configuration then live in the Linux filesystem, and the plumbing is different. We cover that end to end in the Claude Code WSL2 guide.

A rule of thumb: if your code is on C:, run native; if your code lives in ~/ inside a distro, run in WSL. Mixing the two — editing Windows files from inside WSL over /mnt/c — is where performance and path bugs breed.

Install paths and where things live

On native Windows, Claude Code keeps its configuration and session transcripts under your user profile — typically a .claude folder in your home directory, reachable as %USERPROFILE%\.claude in PowerShell or ~/.claude in Git Bash. Inside it you’ll find your settings and the per-project session transcripts that record what you sent and received.

That transcript location matters more than it looks. It’s the raw material for understanding your token usage — and it’s exactly what a Windows-native tool has to read to give you an honest breakdown. Under WSL2 the same files live in the distro’s home directory, not under %USERPROFILE%, which is why a tool built only for native Windows will report “no usage” for a WSL user whose cap is quietly draining. More on that in tracking token usage in WSL2.

PowerShell vs Git Bash gotchas

Both shells run Claude Code fine, but they treat the world differently, and the mismatch is a common source of confusion:

• Path separators. PowerShell speaks Windows paths (C:\Users\you\project); Git Bash speaks POSIX paths (/c/Users/you/project) and silently translates some of them. Scripts that hardcode one style break in the other.
• Quoting. PowerShell and Bash disagree on how quotes and escapes work. A command that a guide wrote for Bash may need different quoting in PowerShell, especially when arguments contain spaces or backslashes.
• Environment variables. Read with $env:NAME in PowerShell, $NAME in Bash. Setting agent config or a custom API endpoint uses different syntax in each.

The fix is simple: pick one shell per project and stay in it. Don’t follow half a tutorial in PowerShell and half in Git Bash — that’s how you end up with a config written to one home directory and read from another.

CRLF and line-ending issues

Windows uses CRLF line endings; Git, Linux, and most build tools default to LF. When Claude Code edits a file, a line-ending mismatch can turn a one-line change into a diff where every line looks modified — noise that’s confusing to review and wasteful to feed back into the model.

Two settings keep this clean. Configure Git’s core.autocrlf deliberately (on Windows, true or input depending on your team’s convention), and set a consistent line-ending rule in your editor or an .editorconfig at the repo root. Do this once per machine and the phantom whole-file diffs disappear. It also keeps your context leaner, because the agent isn’t re-reading files that only look changed.

Path and encoding pitfalls

A few more Windows-specific snags worth knowing:

• Long paths. Deeply nested project paths can exceed the classic Windows path length limit; enabling long-path support avoids obscure failures.
• Spaces in paths. C:\Users\Your Name\... needs careful quoting in both shells.
• Encoding. PowerShell has historically defaulted some output to non-UTF-8 encodings; forcing UTF-8 avoids mangled characters in logs and transcripts.

Keeping your usage under control

Windows developers have long been the underserved half of the Claude Code community: the tooling that helps you see your token burn and cut it was, as of July 2026, largely built for macOS. That’s the gap Hypermile exists to close — a cross-platform usage copilot for Windows (including WSL2), macOS, and Linux — not a Mac-only afterthought.

The practical starting point is measurement. Claude Code’s local transcripts already hold everything you need to break your week into tool output, file re-reads, conversation, and sub-agents. The free hypermile-audit CLI reads them and prints a plain-English report — no upload, open source. From there you know whether your waste is noisy logs, repeated reads, or extra agent context, and you can tackle what Claude Code costs you with specific fixes instead of generic advice.

To understand the caps themselves — the 5-hour window and the weekly ceiling — see how Claude Code usage limits work, plus the 5-hour limit deep-dive and Claude Max limits if those are the pages you need. Running the OpenAI agent too? The same mechanics apply to Codex usage. Weighing tools? Our honest Headroom alternative and Hypermile vs Headroom pages lay out the options for Windows and WSL users, and our Claude usage trackers compared roundup puts the free and paid options side by side.

Next steps

Run the audit below to get your own Windows token breakdown, then download Hypermile that forecasts your cap before you hit it — or read exactly how the compression works first. For the full library, browse all our guides.