Skip to content

Desktop app with WSL

Run Code tab sessions inside a WSL 2 distribution from the Windows desktop app, so Claude uses your Linux toolchain and native paths.

If your projects live inside WSL on Windows, the desktop app can run a Code session inside the distribution rather than on Windows. Claude Code, the tools it calls and git all run on the Linux side, with Linux paths like /home/sam/projects/api, so the session sees exactly the environment your code targets.

Why bother? Editing files under \\wsl.localhost\... from Windows goes over a network filesystem. It is slow, and file watchers (hot reload, test watchers) often miss changes. Running the session inside the distribution avoids both problems. I moved all my Node projects into WSL for this reason and the difference in npm install and test runs is very noticeable.

Requirements

  • Windows 10 or 11 with WSL 2. WSL 1 is not supported.
  • At least one installed distribution, such as Ubuntu.
  • git installed inside that distribution (sudo apt install git on Ubuntu).

Starting a WSL session

  1. Choose the distribution. In the Code tab, start a new session and open the environment picker. Installed WSL 2 distributions are listed under WSL.
  2. Choose a folder. You start in the distribution's home directory. The folder picker browses inside the distribution using Linux paths.
  3. Trust the folder. The first session in a folder shows the workspace trust dialog. Trust is granted per distribution and folder: trusting /home/sam/api in Ubuntu does not trust it in Debian, nor the same path opened from Windows.

The first session in a distribution takes a little longer while Claude sets itself up there. Recent folders are remembered per distribution, so reopening a project is a single click.

Tip: If you pick a \\wsl.localhost\<distro>\... folder from the normal Windows folder picker, Desktop recognises it and reopens it inside that distribution.

What works

Backed by the distribution's own git and toolchain:

  • parallel sessions and worktrees;
  • side chats;
  • visual diff review;
  • branch and pull request status;
  • Open in editor, which launches VS Code connected to the distribution via the Remote - WSL extension.

Not yet available in WSL sessions

  • the integrated terminal;
  • connectors and plugins;
  • session forking;
  • the file browser pane;
  • @ file suggestions in the prompt box.

In the meantime I keep a Windows Terminal tab open on the same distribution for running commands myself.

Managed devices

On organisation-managed machines, WSL sessions may be switched off. If starting a session fails with a message saying the device is managed, that is your administrator's decision; WSL availability is governed separately from other local sessions. Admins should look at how settings reach devices in the admin setup guide.