Claude Code on WSL: my setup for several agents

Step 1 of 12

TL;DR

  • Install Claude Code inside WSL with the native installer, and check which claude doesn’t point into /mnt/c/.
  • Keep projects on the Linux filesystem (~/code), not /mnt/c or a \\wsl.localhost path.
  • For several agents plus Docker on a 32 GB laptop I set memory=20GB, swap=8GB, processors=8 in .wslconfig.
  • VM settings go in %UserProfile%\.wslconfig; per-distro settings ([boot], [interop]) go in /etc/wsl.conf.
  • If every .exe fails with Exec format error, the WSLInterop binfmt entry is gone. Register it again.

It took me several evenings to get Claude Code comfortable on a Windows laptop. Most of the pain came from mixing the Windows and Linux sides of WSL without realising it. This is the setup that stuck: where to install, how big to make the VM when several agents and a Docker stack run at once, and how to let the agent use Windows programs when it needs to. About 40 minutes.

You’ll need

  • Windows 11 with WSL 2 and Ubuntu (check with wsl --version in PowerShell)
  • A Claude account

Install inside WSL, not on Windows

Open the Ubuntu shell and install there, so Claude Code sees the same files, paths and tools as your builds. The native installer is the recommended route and doesn’t need Node; the npm package still exists, but it wants Node 22 or newer. A WSL install doesn't need Git for Windows either.

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

Tip: Run which claude afterwards. WSL adds your Windows PATH by default, so if it points into /mnt/c/, you’re starting a Windows install and things will be slow and strange.

Keep projects on the Linux filesystem

Clone into ~/code, not /mnt/c. File access across the Windows boundary is much slower, and you feel it on every search the agent runs. Claude Code's own troubleshooting page warns that a search across that boundary can return fewer matches than expected, while claude doctor still reports search as OK. Open the folder from VS Code with the WSL extension to edit the same files.

Avoid UNC paths for anything that matters

Paths like \\wsl.localhost\Ubuntu\... work in Explorer, but tools on the Windows side don’t always treat them as local. I lost an afternoon to permission settings that were silently ignored because the project was opened through a UNC path. Start Claude Code from the WSL shell, inside the project folder, every time.

Size the WSL VM for several agents

By default WSL 2 takes half of Windows' memory, every logical processor and a swap file of a quarter of the memory. One agent is fine with that. Several agents, a language server each and a Docker stack are not: the VM runs out of memory first, and Windows slows down with it. My laptop has 32 GB and 12 logical processors. This is my %UserProfile%\.wslconfig:

[wsl2]
memory=20GB
swap=8GB
processors=8
networkingMode=mirrored

20 GB covers the Docker stack and several Claude Code sessions, and leaves 12 GB for Windows. Four processors stay with Windows, so a busy build in WSL has less chance to freeze the desktop. Mirrored networking puts WSL on the same network interfaces as Windows, which makes localhost behave the same on both sides.

Run wsl --shutdown from PowerShell after you change this file, then open Ubuntu again. If the file has an error, WSL starts without it and doesn't say so, so check the result with free -g and nproc.

Put per-distro settings in wsl.conf

.wslconfig holds VM settings for all of WSL. Settings for one distribution go in /etc/wsl.conf inside it. I had [interop] and [network] in .wslconfig at first; Microsoft documents those sections only for wsl.conf. Their defaults are on, which is why I didn't notice. Mine now reads:

[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true

systemd=true lets services start the normal Linux way, which Docker tooling and systemd-binfmt (next step) depend on. The [interop] lines are the defaults; I write them out so the next person knows interop is on by choice. Close every Ubuntu window and wait about 8 seconds, or run wsl --shutdown, for the change to apply.

FileApplies toWhereWhat I setApplied by
.wslconfigThe WSL 2 VM, all distributions%UserProfile% on Windowsmemory, swap, processors, networkingModewsl --shutdown
wsl.confOne distribution/etc/wsl.conf inside itsystemd, interopClose every window and wait about 8 seconds, or wsl --shutdown

Let the agent run Windows programs

With interop on, any .exe runs from the WSL shell, so Claude Code can call powershell.exe, cmd.exe or wsl.exe like any other command. What I use it for:

  • Reading a screen recording or log I saved in Windows Downloads, at /mnt/c/Users/<you>/Downloads/
  • Creating a Windows Task Scheduler reminder with powershell.exe, for jobs that must run when no WSL window is open
  • Writing a small .cmd file that starts wsl.exe -e bash -lc "…", so a Windows shortcut or scheduled task can run a Linux script

Then one day every .exe failed with cannot execute binary file: Exec format error. Installing QEMU's binfmt handlers had replaced the WSLInterop entry that tells the Linux kernel to hand Windows programs to WSL. Check it:

cat /proc/sys/fs/binfmt_misc/WSLInterop

If the file is missing, register the entry permanently, so it survives a restart:

echo ':WSLInterop:M::MZ::/init:PF' | sudo tee /usr/lib/binfmt.d/WSLInterop.conf
sudo systemctl restart systemd-binfmt

The first line of that file must then say enabled.

Small tricks for Windows output

Windows programs write Windows text, and the agent trips on it unless it knows how to read it. Worth a line in your CLAUDE.md:

  • Strip the carriage returns: cmd.exe /c "echo %USERPROFILE%" | tr -d '\r'
  • wsl.exe prints UTF-16, so add tr -d '\0' before you grep its output
  • Turn a Windows path into a WSL path with wslpath: wslpath 'C:\Users\me\Downloads' gives /mnt/c/Users/me/Downloads
  • Windows TEMP leaks into some Node tools. Lighthouse once left C:\Users\...\AppData\Local\lighthouse.* folders in my project. Run such tools with TEMP=/tmp TMP=/tmp.
  • After a Windows restart, wait for Docker Desktop to come up before you start your stack, or the agent finds no Docker and burns a few calls finding out why.

If you also run it on Windows, point it at Git Bash

Running the native Windows build next to WSL is fine. It uses Git Bash for its shell tool when Git for Windows is installed, and falls back to PowerShell when it isn’t. If Git is installed per user, Claude Code may not find it, so set the path explicitly (the env block in settings.json works too).

setx CLAUDE_CODE_GIT_BASH_PATH "C:\Users\me\AppData\Local\Programs\Git\bin\bash.exe"

Learn the settings scopes once

Settings merge from several files, and the most specific wins: ~/.claude/settings.json for you, .claude/settings.json in the project for the team (committed), and .claude/settings.local.json for your private overrides (git-ignored). Put permission rules the whole team needs in the project file, and your own shortcuts in the local one.

{
  "permissions": {
    "allow": ["Bash(bin/magento cache:clean:*)", "Bash(vendor/bin/phpstan:*)"],
    "deny": ["Bash(rm -rf:*)", "Read(./app/etc/env.php)"]
  }
}

Keep powershell.exe and cmd.exe out of the allow list. An agent that can run them can change Windows too, not only the Linux side.

Two settings for long, parallel sessions

With several agents open all day, two environment variables in the env block of ~/.claude/settings.json earn their place:

{
  "env": {
    "CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR": "1",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "300000"
  }
}

The first sends every Bash command back to the project folder, so a cd in one command doesn't send the next one to the wrong place. The second sets how full the context gets, in tokens, before Claude Code compacts it.

Prefer a small bash hook over a clever package

I used an npm package to auto-approve routine prompts. It broke on an update and took my session with it. A ten-line bash script in .claude/hooks/ that I can read does the same job and never surprises me. Keep hooks small, log what they decide, and exit with code 2 only when you mean to block. Other non-zero codes are reported as errors, but the action still goes ahead. One lesson from mine: refuse, don’t rewrite.

Give every repository a CLAUDE.md

Run /init once per project, then edit the file it creates: build and test commands, conventions, and the folders it must never touch. Commit it so everyone shares the same instructions.

Done!

That’s the base setup, sized for more than one agent. Next: running several Claude Code sessions side by side with herdr.

Written by Vishwas Bhatnagar

Technical Architect. Adobe Commerce, marketplaces and AI-assisted engineering.

More about me →

More