›_ Codex Issues
Codex Issues / #18506

Windows Codex app + WSL: UNC cwd breaks terminal, Windows config leaks into WSL, and worktrees need a WSL-native CODEX_HOME

Open 💬 10 comments Opened Apr 18, 2026 by blockedby
💡 Likely answer: A maintainer (github-actions[bot], contributor) responded on this thread — see the highlighted reply below.

Summary

On Windows Codex Desktop with a repository opened from WSL via a UNC path such as:

\\?\UNC\wsl.localhost\Ubuntu-24.04\home\<user>\project

there are three related problems in practice:

  1. The integrated terminal fails to open in the project directory when integratedTerminalShell is set to wsl.
  2. The app continues to use Windows-side config/state in WSL mode.
  3. Worktrees need to live on the WSL filesystem, not under C: / /mnt/c, otherwise performance becomes unacceptable.

I am filing this as a consolidated issue because the current user experience pushes teams into ad-hoc workarounds, and a documented workaround would already help a lot.

Environment

  • Date observed: April 18, 2026
  • Platform: Windows 11 + WSL2
  • Distro: Ubuntu-24.04
  • Repo location: /home/<user>/... inside WSL
  • Project opened in Codex Desktop through \\wsl.localhost\Ubuntu-24.04\home\<user>\...

Problem 1: integrated terminal in WSL mode loses the project cwd

When the project is opened from a WSL UNC path, Codex Desktop appears to pass a Windows UNC path such as:

\\?\UNC\wsl.localhost\Ubuntu-24.04\home\<user>\project

into wsl.exe as the cwd.

In practice, this produces:

wsl: Failed to translate '\\?\UNC\wsl.localhost\Ubuntu-24.04\home\<user>\project'

and the terminal falls back to ~ instead of opening in the repo directory.

Expected behavior

If the project root is inside WSL, the terminal should open directly in the matching Linux directory, e.g.:

/home/<user>/project

Actual behavior

The terminal drops into home, and users need to manually cd back or use a custom wrapper.

Problem 2: Windows config/state still leaks into WSL mode

Even in WSL mode, the app can still reference Windows-hosted config.toml / state instead of the WSL-native location.

This creates confusion about which config is actually active and makes sharing MCP / terminal setup across teammates much harder.

Problem 3: worktrees must live inside WSL

When CODEX_HOME points at the Windows location, worktrees can end up under /mnt/c/Users/<user>/.codex/... instead of a Linux-native directory.

That is a major performance problem for Git-heavy workflows. In real usage, teams keeping repos in WSL want worktrees under something like:

/home/<user>/.codex-app/worktrees/...

not on the Windows filesystem.

Practical workaround that worked for us

1. Keep the agent in WSL, but set the integrated terminal back to PowerShell

Using integratedTerminalShell = "wsl" is the part that breaks terminal startup for UNC-backed WSL repos.

Switching the integrated terminal back to powershell avoids the broken cwd translation path.

2. Force a WSL-native CODEX_HOME only for Codex Desktop

In ~/.profile inside WSL:

# Keep Codex Desktop state/worktrees on the Linux filesystem when the
# Windows app launches its WSL runtime.
if [ "${CODEX_INTERNAL_ORIGINATOR_OVERRIDE:-}" = "Codex Desktop" ]; then
    export CODEX_HOME="$HOME/.codex-app"
fi

Then create the directory once:

mkdir -p ~/.codex-app/worktrees ~/.codex-app/sessions ~/.codex-app/tmp

This keeps worktrees and internal Codex state on the Linux filesystem, which is much faster for WSL-hosted repos.

3. Add a PowerShell helper that jumps from the current UNC path into WSL in the same directory

In the Windows PowerShell profile:

function Enter-WslHere {
    param(
        [string]$Path = (Get-Location).Path
    )

    $p = $Path -replace '^\\\\\?\\UNC\\', '\\'
    if ($p -match '^\\\\wsl(?:\.localhost)?\\([^\\]+)\\(.+)$') {
        $distro = $matches[1]
        $linuxPath = '/' + ($matches[2] -replace '\\', '/')
        wsl.exe -d $distro --cd $linuxPath
        return
    }

    Write-Error "Current path is not a WSL UNC path: $Path"
}

Set-Alias wslhere Enter-WslHere

This gives a reliable bridge:

  • Codex integrated terminal opens as PowerShell in the project UNC path
  • running wslhere opens WSL in the matching Linux project directory

Why this matters

For teams developing in WSL, the current behavior makes the Windows app feel half-configured even when the repo is already correctly placed inside Linux.

The desired setup is straightforward:

  • repo in WSL
  • agent in WSL
  • worktrees in WSL
  • terminal opens in the exact project directory

Today, that still requires manual tweaks and user-discovered workarounds.

Requested improvements

  1. If a project path is a WSL UNC path, convert it to its Linux path before launching wsl.exe for the integrated terminal.
  2. In WSL mode, default the runtime CODEX_HOME / worktree root to a WSL-native location.
  3. Make it unambiguous which config file is active in WSL mode.
  4. If a full fix takes time, document the above workaround in official Windows + WSL guidance.

Related reports

These look closely related:

  • #13549
  • #13762
  • #14461

Happy to provide more exact local details if useful.

View original on GitHub ↗

10 Comments

github-actions[bot] contributor · 3 months ago

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

  • #16815

Powered by Codex Action

blockedby · 3 months ago
Potential duplicates detected. Please review them and close your issue if it is a duplicate. * Codex app on Windows: WSL agent mode fails with: Error creating task Invalid request: AbsolutePathBuf deserialized without a base path #16815 _Powered by Codex Action_

This is a try of workaround. but not a bug report, so it is only partially related

yongkang-yang · 2 months ago

I am seeing what looks like the same class of bug from a different host setup: macOS Codex Desktop connecting remotely to both Windows and WSL over SSH.

Environment

  • Host app: Codex Desktop on macOS
  • Remote targets:
  • Windows host over SSH
  • WSL host over SSH
  • Important detail:
  • the WSL instance is running inside that same Windows machine
  • so from Codex's perspective there are two remote hosts (win and wsl), but they are actually tied to the same physical computer / user environment

I do not know if this is the exact same root cause as the UNC cwd case in this issue, but the symptom pattern is very similar: Windows/WSL path and state leakage across host boundaries.

What I observed

1. Windows remote sometimes shows the WSL directory / project binding

When I connect to the Windows remote and start/open a project there, Codex can end up showing a WSL directory or otherwise behave as if the active workspace binding came from the WSL host.

In practice, the Windows side appears to get “contaminated” by the WSL-side project mapping.

2. Windows remote task creation can fail with:

Invalid request: AbsolutePathBuf deserialized without a base path

This happened while opening a Windows-side conversation/project.

3. Logs suggest WSL paths are being handled while the selected host is Windows

From the macOS Desktop logs, I saw Windows-side activity mixed with WSL-style paths. For example, the app was trying to watch or resolve git paths like /home/... or \home\... while the selected remote host was the Windows remote.

That strongly suggests stale or leaked workspace/cwd/git-watcher state across remote hosts.

4. Auth state also drifted separately across the remote hosts

I also hit the related remote auth problem where WSL-side Codex was still using stale auth state even though local/macOS auth had already refreshed. Syncing auth fixed WSL, but the Windows/WSL workspace-binding issue remained a separate problem.

So in my case there seem to be two layers:

  1. auth/state divergence across local / Windows / WSL
  2. Windows/WSL workspace mapping leakage inside Desktop app state

What made this especially suspicious

A local restore of the macOS-side Desktop state file:

~/.codex/.codex-global-state.json

temporarily fixed the Windows-vs-WSL remote mapping.

That makes this look less like a project-specific problem and more like a Desktop-side remote-project / workspace-binding state corruption issue.

Why I think this is related to this issue

This issue describes Windows/WSL boundary problems where:

  • Windows-side state leaks into WSL mode
  • cwd/path resolution crosses the wrong boundary
  • Codex gets confused about which filesystem model it is working in

My setup is different because the host app is macOS, but the underlying failure mode seems closely related:

  • one logical Windows environment
  • one logical WSL environment
  • Codex stores/manages them as separate remotes
  • eventually path/workspace state crosses the boundary and the wrong host/path model is used

Practical takeaway

Even when the app is not running on Windows directly, Codex Desktop appears fragile when both of these are present at the same time:

  • a Windows remote target
  • a WSL remote target backed by that same Windows machine
eschulma · 2 months ago

I don't know if this is the right solution or not, but frankly working with the app in WSL is still something of a nightmare. In our case the main issue is that diffs are broken.

blockedby · 2 months ago

honestly, I moved off to other agent harness, and installed kubuntu as daily driver =)

RickyLoynd · 2 months ago

Probably related: I just installed the Codex App today (26.422.30944), to use on my repos in WSL. As shown in this image, I was able to set the agent environment to WSL, but the integrated terminal shell won't let me select WSL. It seems frozen on PowerShell. And probably as a result of that, when I ask Codex to run a Git command it tries to use Git from PowerShell instead of WSL Git, which leads to errors.

<img width="866" height="511" alt="Image" src="https://github.com/user-attachments/assets/a76f240f-aa18-4048-a1f8-7264e437ca08" />

satyalyadav · 2 months ago

I can reproduce the Windows-side CODEX_HOME behavior on Codex Desktop for Windows with WSL mode enabled. This was generated by Codex:

Environment:

  • Codex Desktop: 26.506.3741.0
  • Windows: 10.0.26200.8246
  • WSL: 2.6.3.0
  • Distro: Ubuntu 24.04.4 LTS
  • Kernel: 6.6.87.2-microsoft-standard-WSL2

What I observed:

  • The WSL app-server was launched from the Windows-side Codex path:

/mnt/c/Users/<user>/.codex/bin/wsl/codex app-server --analytics-default-enabled

  • Inside the WSL agent, CODEX_HOME was:

/mnt/c/Users/<user>/.codex

  • Startup in WSL mode was much slower than Windows-native mode.

What improved it:

  • For Codex Desktop-launched WSL sessions only, overriding:

CODEX_HOME=/home/<user>/.codex-app

  • Creating the WSL-native Codex home directories under:

/home/<user>/.codex-app

  • Opening active projects from WSL-native paths under:

/home/<user>/...
instead of:
/mnt/c/...

After this, startup felt much better.

I also found a separate local shell startup issue in my own ~/.bashrc, so I am not treating that part as a Codex bug. The Codex-specific issue appears to be that WSL mode inherits the Windows-side CODEX_HOME, which pushes runtime state/worktree-related paths onto /mnt/c.

MisterRound · 2 months ago

Additional current evidence from Windows Desktop + WSL mode:

  • Desktop package: OpenAI.Codex_26.506.3741.0_x64__2p2nqsd0c76g0
  • WSL: 2.7.3.0, kernel 6.6.114.1-1
  • Codex WSL binary: /mnt/c/Users/<user>/.codex/bin/wsl/codex
  • Runtime CODEX_HOME=/mnt/c/Users/<user>/.codex
  • Active Desktop root after launch: C:\Users\<user>\.codex
  • Saved project roots include WSL UNC paths such as \\wsl.localhost\Ubuntu\home\<wsl-user>\...

The WSL IO performance toast appears on app launch, regardless of which project is later selected, because the WSL app-server/runtime starts from the Windows-mounted Codex home and cwd. Repos can be correctly placed under /home/<wsl-user>/..., but runtime/cache/tmp/helper paths are still under /mnt/c/Users/<user>/.codex.

I tested the CODEX_INTERNAL_ORIGINATOR_OVERRIDE=Codex Desktop + CODEX_HOME=/home/<wsl-user>/.codex-app workaround. It is directionally correct for IO/worktree performance, but I reverted it because it creates a risky split-brain state between Windows Desktop UI/config and WSL app-server runtime/config. This really needs a first-class product setting or default split between Windows UI state and WSL-native runtime/worktree/cache roots.

AxENSRennes · 2 months ago

Same issue here on Windows. Since WSL is the main reason I want to use the desktop app, this makes the app pretty hard to use reliably. Would really appreciate a fix.

julesLubrano · 9 days ago

Additional sanitized reproduction on a current Windows Store build:

Codex Desktop: 26.707.3748.0
Bundled WSL Codex: 0.144.0-alpha.4
Platform: Windows 11 x64 + WSL2 Ubuntu
Repositories: WSL-native paths under /home/<linux-user>/...

Desktop persisted three WSL repositories in electron-saved-workspace-roots as UNC values:

\\wsl$\Ubuntu\home\<linux-user>\workspace\labs\<repo-a>
\\wsl$\Ubuntu\home\<linux-user>\workspace\labs\<repo-b>
\\wsl$\Ubuntu\home\<linux-user>\workspace\projects\<repo-c>

I tested replacing one saved root with its canonical POSIX value:

/home/<linux-user>/workspace/labs/<repo-a>

For ten minutes after the edit:

  • the POSIX value remained present;
  • no new EISDIR watcher event appeared;
  • the logs database did not grow;
  • the repository branch, HEAD, and worktree state remained unchanged.

After changing a second root to POSIX, Desktop rewrote its in-memory workspace state back to disk and restored all three UNC values, including the first root that had passed the ten-minute canary.

This suggests the problem is not only initial UNC-to-WSL conversion. Desktop also retains an authoritative in-memory representation and can overwrite canonical POSIX paths written to .codex-global-state.json.

Expected behavior:

  • WSL repositories should be persisted as /home/... paths when the app-server runs in WSL;
  • Desktop should not convert or restore them to UNC paths;
  • if direct state-file edits are unsupported, the product should expose a supported way to rebind an existing saved WSL workspace to its canonical POSIX root.

No repository or worktree corruption occurred during this test. The test was stopped as soon as the UNC values returned.