Claude Code WSL2: setup and performance guide

Short answer: Claude Code on WSL2 is a full Linux environment on Windows: install a WSL2 distro, put the project in the Linux home directory, and run Claude Code from inside that distro. Setup is the easy part. Performance is the part most guides skip — the usual slowdown is working on files stored under /mnt/c (the mounted Windows drive) from inside WSL2. Keep the hot project in ~/ instead, and WSL2 is fast. This is the WSL2 setup and performance companion to our Claude Code on Windows hub.

Why WSL2 for Claude Code

WSL2 runs a real Linux kernel on your Windows machine, which means Claude Code gets a genuine Unix environment: Linux build tools, POSIX shells, and the workflows most tutorials assume. If your project already expects Linux — Docker, native compilers, shell scripts — running Claude Code inside the distro removes a whole class of cross-platform friction you’d otherwise fight on native Windows.

Setup, step by step

1. Install WSL2 and a distribution. Use a current WSL2 release; the recent versions bring better networking and file-access behavior that matter for a local proxy.
2. Open the distro’s shell. Everything below happens inside the Linux environment, not in PowerShell.
3. Put your project in the Linux home directory. Clone or move your repo to ~/projects/..., not to a path under /mnt/c. This one choice is the difference between fast and slow — see below.
4. Install Claude Code inside the distro and run it from there, so it reads and writes to the native Linux filesystem.
5. Confirm your config location. Inside WSL2, Claude Code keeps its settings and transcripts in the distro’s home directory (for example ~/.claude), not under your Windows %USERPROFILE%.

The performance rule that matters most

Here’s the mistake that makes people think WSL2 is slow: working on files stored on the Windows drive (/mnt/c/...) from inside the distro. Cross-filesystem access between the Windows host and the Linux guest is dramatically slower than the distro’s own filesystem. An agent that reads and writes many files — exactly what Claude Code does — feels that penalty on every operation.

The fix is simple and total: keep the files you actively work on in the Linux home directory. Reserve /mnt/c for occasional interop, not for your hot project. Do this and WSL2 is fast; ignore it and no amount of configuration will save you.

Networking and the local proxy

If you use a usage copilot that compresses prompts, it runs a small local proxy that Claude Code has to reach. On a single OS that’s simple. Across the Windows/WSL boundary it isn’t — networking modes differ, and assuming plain localhost everywhere is the kind of shortcut that breaks silently. Hypermile is built to auto-detect the WSL networking mode and wire Claude Code correctly, and to get out of the way cleanly if anything goes wrong.

Config and transcript paths

Because Claude Code writes to the distro’s home directory in WSL2, your token history lives there too — in the JSONL transcripts under ~/.claude. That’s why a Windows-native usage tool reports nothing for WSL users: it’s looking in the wrong filesystem entirely. Any honest audit has to read inside the distro, using the distro’s real path. We go deeper on this in tracking Claude Code token usage in WSL2.

Keeping usage under control in WSL2

WSL2 developers hit the same weekly-cap pain as everyone else, just with harder plumbing underneath. The starting point is measurement: the free hypermile-audit CLI runs inside your distro and reads the transcripts where they actually live, then prints a plain-English breakdown of where your tokens went — no upload, open source. Once you can see whether the waste is noisy logs or repeated file reads, the fixes get concrete.

Run the audit below, then download Hypermile — WSL support included. For the caps themselves, see how Claude Code usage limits work; for the native-Windows side, head back to the Claude Code on Windows hub.