Junie on WSL — known issues and workarounds

Problem

Junie does not work correctly when the project is located on WSL (Windows Subsystem for Linux). Typical symptoms include: Junie hanging on “Working” / “Thinking” when the project is opened via a \wsl.localhost... path, Junie using Windows-style paths or commands instead of Linux ones, terminal commands that never complete, or Junie not loading / hanging when used with Remote Development (IDE Gateway / devcontainer) on WSL.

Cause

Most probable causes:

1. Project accessed via a mounted WSL path When the project is opened from Windows through a mounted WSL share (for example, \wsl.localhost...), Junie may hang on “Working” / “Thinking”.

   Related issue: Junie stuck in "Working" step when using mounted wsl instance.

2. Junie chooses Windows paths/commands instead of Linux ones Even with explicit guidelines in .junie/guidelines.md, Junie may fall back to PowerShell / Windows-style paths and commands instead of using the Linux environment inside WSL.

   Related issue: Junie does not perform WSL2 commands on Windows.

3. Terminal commands hang in WSL Commands like ls may run indefinitely in the Junie terminal with no output and no reaction to Ctrl+C when executed against a WSL environment.

   Related issue: Junie terminal commands hang in WSL.

4. Remote Development with WSL is not supported When using Remote Development (IDE Gateway / devcontainer) together with WSL, Junie may not load at all or may hang during initialization.

   Related issue: Support Remote Development with Junie.

5. Native WSL2 support is still on the roadmap First-class, native WSL2 support for Junie is tracked separately and is not yet fully implemented.

   Related issue: Make Junie support WSL2.

Resolution

Before escalating, check the known issues and suggested workarounds below.

1. Junie hangs on “Working” / “Thinking” with a mounted WSL path Symptom: Project is opened from Windows via a \wsl.localhost... (or similar) path and Junie gets stuck on “Working” / “Thinking”.

   Workaround: Run the IDE from inside WSL via WSLg instead of accessing the project through the mounted WSL share.

2. Junie uses Windows paths or PowerShell instead of Linux Symptom: Even with .junie/guidelines.md configured for Linux, Junie still generates Windows-style paths or PowerShell commands.

   Workaround:

   • Confirm that the IDE and Junie are actually running inside the WSL environment rather than on the Windows host.
   • If the IDE must run on Windows, prefer accessing the project via native Windows paths instead of WSL mounts, or move the project to a non-WSL location until native WSL2 support is available.

3. Terminal commands hang in WSL Symptom: Simple commands like ls hang indefinitely in Junie with no output, and Ctrl+C does not interrupt them.

   Workaround: Restart the affected WSL distribution from Windows:

   wsl -t <distro name>
   
   

   shell

   Then reopen the IDE / Junie and re-test.

4. Remote Development with WSL (IDE Gateway / devcontainer) doesn’t work Symptom: Junie does not load or hangs when used in Remote Development setups that involve WSL (for example, IDE Gateway or devcontainers running under WSL).

   Workaround:

   • Use Junie only in a supported, non-Remote-Development setup for now (e.g., a local project on Windows or an IDE running directly inside WSL via WSLg).
   • Track Support Remote Development with Junie for updates on Remote Development + WSL support.

5. None of the above applies (new / unclear WSL issue) If your Junie-on-WSL problem does not match any of the scenarios above, treat it as a new case related to the broader “native WSL2 support” roadmap item.

   When reporting such issues, please include:

   • WSL version.
   • Linux distribution and version (for example, Ubuntu 24.04).
   • IDE: name and full build number of the Windows-host IDE.
   • Junie plugin version.
   • Whether the project is:
     • Mounted from Windows (for example, \wsl.localhost...), or
     • Opened in an IDE that runs inside WSL (for example, via WSLg).