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

[blockedby]

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:

• Codex App on Windows, when configured to use WSL, continues to reference the Windows-hosted config.toml #13549
• Windows desktop in WSL mode uses the Windows CODEX_HOME inside WSL and creates/stores worktrees on /mnt/c instead of the WSL filesystem #13762
• Windows Codex cannot start when WSL mode is enabled (terminalShell=wsl) #14461

Happy to provide more exact local details if useful.

[github-actions]

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

[blockedby]

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](https://github.com/openai/codex/issues/16815)

Powered by Codex Action

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

[yongkang-yang]

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]

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.