[Feature Request] Native WSL Remote Integration for Claude Code Desktop on Windows

[matheuspimentaa]

Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Summary

Add native WSL (Windows Subsystem for Linux) remote integration support to Claude Code Desktop on Windows, similar to the "Remote - WSL" approach used by VS Code. The goal is to allow Claude Code to connect to a WSL distribution and run the entire development environment — including the Claude Code agent, its commands, the integrated terminal, and any spawned processes — inside WSL, rather than running on Windows and simply reading files from the \\wsl$\ or \\wsl.localhost\ network share.

Problem / Motivation

Currently, when a developer opens a WSL project in Claude Code Desktop on Windows, the IDE effectively runs on the Windows side and accesses the Linux filesystem through the \\wsl$\ / \\wsl.localhost\ UNC path. This leads to several practical issues for developers whose real working environment is WSL (Ubuntu, Debian, Arch, etc.):

1. Wrong shell / wrong toolchain. The integrated terminal and any commands executed by Claude Code (tests, builds, package managers, git hooks, linters, formatters, etc.) run under Windows using PowerShell/cmd, instead of the native Unix shell (bash/zsh/fish) inside WSL. Tooling installed only inside WSL (nvm, pyenv, asdf, rbenv, system packages via apt, Docker inside WSL, etc.) is not available or behaves inconsistently.

2. Path and line-ending mismatches. Tools end up seeing Windows-style paths (\\wsl.localhost\Ubuntu\home\user\project) instead of native Linux paths (/home/user/project). This breaks scripts, Makefiles, Docker volume mounts, symlinks, file watchers, and anything that depends on POSIX semantics or case-sensitive filesystems.

3. Performance penalties. Reading/writing files across the 9P protocol from Windows into the WSL filesystem is significantly slower than operating natively inside WSL. For large repositories, running Claude Code tasks (indexing, grep-like searches, test runs) is noticeably slower and can hit file-watch limits.

4. Permissions and environment drift. File permissions, UID/GID ownership, environment variables, $PATH, $HOME, SSH agents, GPG agents, and shell profiles (.bashrc, .zshrc, .profile) defined inside WSL are not respected when Claude Code runs from the Windows side. This causes features like git signing, SSH-based remotes, or credential helpers to fail or behave differently than in the developer's real shell.

5. Mismatch with developer expectations. Many developers use WSL precisely because their project targets Linux (containers, CI, production). They expect Claude Code's agent to reason about and operate on the project in the exact same environment their Linux tooling uses — not through a Windows-side proxy.

Proposed Solution

Introduce a first-class "Connect to WSL" mode in Claude Code Desktop for Windows, conceptually equivalent to VS Code's Remote - WSL:

• A command / entry point such as "Claude Code: Connect to WSL..." that lets the user pick an installed WSL distribution (e.g., Ubuntu-22.04, Debian) and a target folder using Linux paths (/home/user/project).
• When connected, Claude Code installs and runs a lightweight remote server component inside the chosen WSL distribution. The desktop app on Windows becomes a thin UI client that talks to this server over a local channel (e.g., localhost socket / named pipe / stdio through wsl.exe).
• All "backend" work happens inside WSL:
  • The Claude Code agent process and its tool executions run inside WSL.
  • The integrated terminal is a real Unix shell (user's default login shell inside WSL, honoring /etc/passwd and shell rc files).
  • File reads/writes, searches, diffs, and edits use the native Linux filesystem at Linux paths.
  • Commands invoked by Claude Code (build, test, run, lint, format, git, package managers, Docker, etc.) execute inside WSL, using the Linux $PATH and environment.
• Opening a project via \\wsl$\... or \\wsl.localhost\... should detect the WSL origin and offer to reopen the folder in WSL remote mode.
• Support opening a WSL folder directly from the Linux side via a CLI entry point (e.g., something analogous to code . but for Claude Code) so users can run it from inside their WSL shell and have the desktop UI attach to that session.
• Respect the user's WSL configuration: default distribution, default user, /etc/wsl.conf, environment variables, and shell startup files.
• Provide clear status indicators in the UI showing: "Connected to WSL: Ubuntu-22.04", current Linux working directory, and the shell being used.

User Experience Goals

• From the user's perspective, once connected, Claude Code "is" running in Linux: terminals are bash/zsh, paths are /home/user/..., tools are the ones installed via apt, brew (linuxbrew), nvm, pyenv, etc.
• The PowerShell/cmd environment on Windows is not involved in executing project commands.
• Reconnecting to a recently used WSL workspace should be a single click.

Alternatives Considered

• Current behavior (accessing \\wsl.localhost\... from Windows). Works for simple editing but fails for serious development due to the issues listed above.
• Running Claude Code entirely inside WSL as a Linux app (e.g., via WSLg). Viable for some users, but adds friction (GUI-in-WSL setup, different install path, separate updates) and does not match the expected Windows-desktop experience. A remote model gives the best of both: native Windows UI + native Linux backend.
• Manually launching Claude Code CLI inside WSL and a separate Windows UI. Fragmented workflow, no unified UX, and hard to keep in sync with the desktop app.

Additional Context

• Prior art: VS Code's Remote - WSL extension, JetBrains IDEs' WSL backend support, and Cursor's WSL remote mode. These are widely adopted precisely because developers want the IDE/agent to operate natively inside WSL.
• This feature would be especially valuable for users working on Linux-first stacks (Node.js, Python, Go, Rust, Ruby, Docker/Kubernetes, ML workflows) from a Windows machine.
• Ideally, this should also play well with Claude Code's agent capabilities, so that when the agent runs commands, it does so inside WSL with the correct shell, environment, and filesystem semantics — not through PowerShell.

Impact

Enabling native WSL remote integration would make Claude Code Desktop a genuinely viable primary tool for Windows-based developers whose real environment is Linux, eliminate an entire class of path/shell/environment bugs, significantly improve performance on WSL projects, and bring parity with other modern IDEs that already support this workflow.

Proposed Solution

Add a first-class "Connect to WSL" mode to Claude Code Desktop on Windows, analogous to VS Code's Remote - WSL extension.

Desired user flow:

1. In Claude Code Desktop, the user opens a command palette / menu entry such as "Claude Code: Connect to WSL..." and picks an installed WSL distribution (e.g., Ubuntu-22.04, Debian) and a target Linux folder (e.g., /home/user/projects/my-app).
2. Claude Code installs (on first use) and runs a lightweight remote server component inside the selected WSL distro. The Windows desktop app acts as a UI client talking to that server over a local channel (stdio via wsl.exe, a UNIX socket, or a localhost port).
3. From that point on, the entire Claude Code backend runs inside WSL:
   • The Claude Code agent process runs in Linux.
   • The integrated terminal is the user's default Unix shell (bash/zsh/fish), honoring .bashrc, .zshrc, /etc/profile, etc.
   • File reads, writes, searches, and diffs happen on the native Linux filesystem using Linux paths (/home/user/...), not \\wsl.localhost\....
   • Every command Claude Code invokes (tests, builds, linters, formatters, git, npm, pnpm, pip, poetry, cargo, go, docker, etc.) is executed inside WSL with the Linux $PATH and environment — never through PowerShell or cmd.
4. A status indicator in the UI clearly shows the remote context, e.g. WSL: Ubuntu-22.04 — /home/user/projects/my-app — shell: zsh.
5. A CLI entry point from inside WSL (similar to VS Code's code .) lets the user run e.g. claude . in their Linux shell and have the Windows desktop UI attach to that WSL session.
6. Opening a project via \\wsl$\... or \\wsl.localhost\... triggers a prompt: "This folder is inside WSL. Reopen in WSL?" — one click switches to remote mode.
7. Recent WSL workspaces are remembered and can be reopened in one click, reconnecting to the correct distro and path.

Key requirement: when the user interacts with Claude Code in this mode, it must feel exactly like running Claude Code natively inside Linux — the Windows side is only responsible for rendering the UI and forwarding input/output.

Alternative Solutions

1. Current behavior — opening WSL folders via \\wsl$\ / \\wsl.localhost\ from Windows. Claude Code runs on Windows and only reaches into WSL through the 9P network share. Commands execute in PowerShell/cmd, paths are Windows UNC paths, and WSL-installed toolchains (nvm, pyenv, apt packages, Docker in WSL, etc.) are not properly available. This is the scenario this feature request wants to replace.

2. Running Claude Code entirely inside WSL as a Linux GUI app (via WSLg). Technically possible for some users, but requires a separate Linux install of Claude Code, different update channel, and GUI-in-WSL setup. It also breaks the "Windows desktop app" UX that most Windows users expect. Not a good general solution.

3. Using Claude Code CLI inside WSL plus a separate Windows UI. Fragmented workflow: two disconnected surfaces, no unified session, harder to keep versions and settings in sync, and poor discoverability for new users.

4. Third-party wrappers / manual scripts that invoke wsl.exe for specific commands. Fragile, doesn't cover the full agent surface (terminal, file I/O, watchers, subprocesses), and every user has to re-implement it. Should be solved once, officially, inside Claude Code.

A proper remote-WSL architecture (like VS Code's) is the only alternative that cleanly solves all of these issues at once.

Priority

Critical - Blocking my work

Feature Category

Other

Use Case Example

Scenario: Full-stack developer on Windows targeting Linux

1. I use Windows 11 as my daily OS but all my development happens inside WSL2 (Ubuntu 22.04), where I have nvm, pnpm, pyenv, poetry, Docker (Linux engine), and my SSH/GPG keys configured. My project lives at /home/matheus/projects/my-app and targets a Linux production environment.
2. I open Claude Code Desktop on Windows and choose "Connect to WSL..." → Ubuntu-22.04 → /home/matheus/projects/my-app.
3. Claude Code installs its remote server in WSL (first time only) and opens the project. The status bar shows WSL: Ubuntu-22.04 — /home/matheus/projects/my-app — shell: zsh.
4. I open the integrated terminal. It is a real zsh session inside WSL, with my .zshrc, my aliases, nvm loaded, and node -v returning the version I installed in Linux — not the Windows one.
5. I ask Claude Code to "run the test suite and fix the failing tests." The agent runs pnpm test inside WSL, sees Linux paths in stack traces, edits files on the Linux filesystem, and re-runs the tests — all without ever touching PowerShell.
6. I ask it to "spin up the dev environment." It runs docker compose up -d against the Linux Docker engine inside WSL. Volume mounts use native Linux paths and work correctly.
7. I commit with git commit -S. GPG signing works because the agent is using the GPG agent configured in my WSL user profile.
8. I close Claude Code, reopen it later, click the recent workspace entry, and I'm instantly back in the same WSL remote session.

Throughout this flow, I never had to deal with path translation, PowerShell quirks, broken symlinks, missing Linux tools, or slow file access over \\wsl.localhost\. The experience matches what I already get from VS Code Remote - WSL, but with Claude Code's agent capabilities fully integrated into the Linux environment.

Additional Context

Prior art and references

• VS Code Remote - WSL: https://code.visualstudio.com/docs/remote/wsl — the canonical implementation of this pattern; widely adopted because it solves exactly the problems described here.
• JetBrains IDEs WSL support: https://www.jetbrains.com/help/idea/how-to-use-wsl-development-environment-in-product.html
• Cursor and other Electron-based editors have followed the same remote-WSL model.

Why this matters for Claude Code specifically

Claude Code is agentic — it doesn't just edit files, it runs commands, inspects output, iterates on tests, and executes tooling. That makes the "which environment do commands actually run in?" question much more important than for a plain editor. If the agent runs npm test in PowerShell against a \\wsl.localhost\... path while the user's real toolchain, Docker, and CI all live in Linux, the agent's feedback loop becomes unreliable. Running the agent inside WSL fixes this at the root.

Environments to consider

• WSL1 and WSL2 (WSL2 is the primary target; WSL1 can be best-effort).
• Multiple installed distributions (Ubuntu, Debian, Arch, Kali, custom distros).
• Non-default users and custom /etc/wsl.conf settings.
• Shells other than bash (zsh, fish) and tools like direnv, asdf, mise.

Nice-to-haves (follow-ups, not required for the MVP)

• Remote support beyond WSL (SSH, dev containers) using the same architecture.
• Per-workspace remote configuration files checked into the repo.
• Ability for the agent to surface "this command will run inside WSL as user X with shell Y" before executing, for transparency.

Summary

Please treat native WSL remote integration as a core platform feature for Claude Code Desktop on Windows. It would remove a major friction point for a large segment of professional developers and bring Claude Code to parity with other modern IDEs on this exact workflow.

[panfiva]

Just installed Claude desktop yesterday to learn it does not integrate with claude-code running in WSL. My use cases are as follows:

1. I should be able to start Claude desktop inside WSL by running a command in shell and/or by running /desktop inside Claude code; A thin Windows client should launch using all preferences, skills and other configs from WLS.
2. I should be able to easily find Claude project directory for each project created inside Claude Desktop. This will make it easier to edit project configurations (instructions and files) using VS Code and version control them.

There is a similar request (#12506), however it seems this request focuses on the key need that we have (native integration into WSL) instead of just running commands remotely in WSL.

+1 on this feature request

[hdomos]

Also just installed Claude desktop and learnt it cannot be used easily with wsl. I have a linux stack that I use for development currently with VS code and its wsl integration but I would really like to switch to claude code.

I would like to use claude desktop as a mission control for running several worktree based sessions inside WSL in multiple projects at once.

[p-clements]

This is absolutely required. Codex already offers this as well as VSCode as mentioned by the OP.

[rclanan]

Can we please get this on the roadmap? I love that it has ssh support but native WSL support as well would be amazing!

[JordanRL]

Considering that Claude Code is supposed to be a professional development environment, and that I sometimes get prompted to update my Claude Desktop multiple times in a single day, it's absolutely dumbfounding that this feature hasn't been included yet. Claude Desktop is basically just a toy until this feature lands.

[gowanuslobster]

There is a cluster of issues that makes it seem like Anthropic / Claude generally speaking does not want to support Windows/WSL connectivity. This issue, the UNC path issue referenced above, the fact that Claude Code TUI in WSL doesn't support simple copy/paste of images, etc. Please Anthropic, this should be so easy! Just have Claude implement these features! In fact has to be a PR somewhere already that gets this right... Just have Claude find it for you & merge it!

[bertPB]

$965B Company everyone...

[RyanEwen]

I should have done more research when switching to Claude.. I was a bit shocked to find no WSL nor dev container support. All of our company's projects use dev containers...