---
name: wsl-interop
description: Decide when to use WSL vs native Windows and bridge paths/commands correctly. Use when projects assume Linux, Docker Desktop WSL backend, bash scripts, line endings in dual environments, or the user mentions WSL, Ubuntu on Windows, or /mnt/c paths.
license: MIT
metadata:
  author: javeckbila
  version: "1.0.0"
  platform: windows
---

# WSL interop for coding agents

## Decision: native Windows vs WSL

| Stay on native Windows | Use WSL |
|------------------------|---------|
| .NET, WinUI, PowerShell modules, IIS | Linux-only toolchains, bash-heavy repos |
| Pure Node/Python apps with Windows support | Scripts hard-coded to `/usr/bin` or apt |
| User works in PowerShell/Codex on Windows | User explicitly develops inside WSL |
| Editing files under `C:\...` with Windows IDEs | Need native Linux sockets, systemd, etc. |

**Do not force WSL** for simple Node/Python apps that already work on Windows.

## Detect WSL

```powershell
wsl --status
wsl -l -v
```

Inside a shell, WSL often has:

```bash
uname -a   # contains Microsoft / WSL
echo $WSL_DISTRO_NAME
```

## Path bridge

| Windows | WSL |
|---------|-----|
| `C:\Users\Ada\proj` | `/mnt/c/Users/Ada/proj` |
| `\\wsl$\Ubuntu\home\ada` | `/home/ada` |

```powershell
wsl wslpath -a 'C:\Users\Ada\proj'
wsl wslpath -w '/home/ada/proj'
```

### Performance rule (important)

- Store **Linux-native projects** in the WSL filesystem (`\\wsl$\...` / `/home/...`)
- Store **Windows-native projects** on `C:\`
- Avoid heavy `npm install` / `git status` across `/mnt/c` (slow + file watcher pain)

## Running commands

```powershell
# One-shot Linux command from Windows
wsl -- cd /home/ada/proj '&&' npm test

# Preferred: open a WSL shell in the right distro
wsl -d Ubuntu -- bash -lc 'cd ~/proj && npm test'
```

Quote carefully. Prefer `bash -lc '...'` for login PATH.

## Git and line endings across worlds

- Same repo mounted in both OS views can confuse tools
- Stick to **one primary environment** per repo
- Use `.gitattributes` with `eol=lf` for cross-platform codebases

## Docker Desktop + WSL

- Integration often binds a specific distro
- `docker` in WSL may talk to Docker Desktop's engine
- Compose file paths differ by shell — keep them consistent

## File permissions and executables

- `chmod +x` only matters inside WSL/Linux
- Windows NTFS mounts may not preserve Unix modes as expected

## Agent playbook

1. Ask (or detect): is this a WSL-first repo?
2. If WSL-first: run builds/tests via `wsl ...`, edit via `\\wsl$\` or remote WSL in the IDE
3. If Windows-first: use `pwsh`, native toolchains, avoid `/mnt/c` thrash
4. Never rewrite a working Windows workflow into WSL "for purity"
5. Never store secrets in world-readable `/mnt/c` copies carelessly

## When interop fails

| Problem | Fix |
|---------|-----|
| `wsl` not found | Install WSL / enable feature (needs user) |
| Command not found inside WSL | Install tools *in the distro*, not Windows PATH |
| CRLF breaks shell scripts in WSL | `.gitattributes` + `dos2unix` if needed |
| Slow Node on `/mnt/c` | Move repo to `~/code` in WSL |