codex - 💡(How to fix) Fix VS Code extension WSL agent fails when Windows and WSL share CODEX_HOME on C drive SQLite state

What version of the IDE extension are you using?

26.519.32039

What subscription do you have?

Plus

Which IDE are you using?

VS Code

What platform is your computer?

Windows x64 with WSL2 Ubuntu-24.04

What issue are you seeing?

When the VS Code Codex extension is configured with:

Agent environment: Windows Subsystem for Linux

the extension launches the WSL Codex app-server through wsl.exe and tries to initialize SQLite state under the shared WSL CODEX_HOME:

/home/lawrence/.codex

Because this path is a symlink to the Windows C-drive Codex home:

/mnt/c/Users/Artoria/.codex

the WSL Linux Codex binary and Windows Codex binary end up sharing the same SQLite state databases on:

/mnt/c

This causes the WSL app-server to fail with errors like:

Error: failed to initialize sqlite state runtime under /home/lawrence/.codex:
failed to initialize state runtime at /home/lawrence/.codex:
error returned from database: (code: 4618) disk I/O error

or:

Error: failed to initialize sqlite state runtime under /home/lawrence/.codex:
failed to initialize state runtime at /home/lawrence/.codex:
migration 1 was previously applied but has been modified

In VS Code extension logs, the WSL launch command looked like:

wsl.exe -d Ubuntu-24.04 -- /usr/bin/bash -lc /usr/bin/env \
'PATH=/mnt/c/Users/Artoria/.vscode/extensions/openai.chatgpt-26.519.32039-win32-x64/bin/linux-x86_64:$PATH' \
RUST_LOG=warn \
CODEX_INTERNAL_ORIGINATOR_OVERRIDE=codex_vscode \
/mnt/c/Users/Artoria/.vscode/extensions/openai.chatgpt-26.519.32039-win32-x64/bin/linux-x86_64/codex \
app-server --analytics-default-enabled

Windows native mode still works:

codex doctor --summary

13 ok · 1 idle · 1 notes · 0 warn · 0 fail ok

But WSL mode fails unless CODEX_SQLITE_HOME is set to a WSL-native directory.

What steps can reproduce the bug?

1. On Windows, use the VS Code Codex extension.

2. Use a shared Codex home between Windows and WSL:

   C:\Users\Artoria\.codex
   /home/lawrence/.codex -> /mnt/c/Users/Artoria/.codex

3. Open Codex extension settings.

4. Set:

   Agent environment: Windows Subsystem for Linux

5. Let VS Code reload.

6. Open the Codex sidebar / start the extension.

7. The WSL app-server fails during SQLite state runtime initialization.

The same failure can be reproduced from WSL without the workaround:

wsl.exe --distribution Ubuntu-24.04 -- /usr/bin/bash -lc \
'/mnt/c/Users/Artoria/.vscode/extensions/openai.chatgpt-26.519.32039-win32-x64/bin/linux-x86_64/codex doctor --summary'

It reports:

state database integrity check failed

What is the expected behavior?

The VS Code extension should support Windows + WSL usage without both platforms fighting over the same SQLite files on /mnt/c.

Expected behavior would be one of:

1. The extension automatically sets a WSL-local CODEX_SQLITE_HOME when launching WSL agent mode.
2. The extension exposes a setting for WSL CODEX_SQLITE_HOME.
3. Codex automatically avoids storing SQLite state under /mnt/c/.../.codex when running inside WSL.
4. Documentation explains the recommended Windows + WSL split-state setup.

A working layout is:

Windows:
  CODEX_HOME = C:\Users\Artoria\.codex

WSL:
  CODEX_HOME = /home/lawrence/.codex -> /mnt/c/Users/Artoria/.codex
  CODEX_SQLITE_HOME = /home/lawrence/.codex-sqlite

This preserves shared auth/config/sessions while keeping SQLite state platform-local.

Additional information

Current workaround:

Create:

/home/lawrence/.codex-wsl-env

with:

export CODEX_SQLITE_HOME="$HOME/.codex-sqlite"

For VS Code Windows extension WSL agent mode, source it from:

/home/lawrence/.profile

[ -f "$HOME/.codex-wsl-env" ] && . "$HOME/.codex-wsl-env"

For VS Code Remote-WSL mode, source it from:

/home/lawrence/.vscode-server/server-env-setup

[ -f "$HOME/.codex-wsl-env" ] && . "$HOME/.codex-wsl-env"

After applying this workaround, the WSL Linux Codex binary passes state initialization:

codex doctor --summary

11 ok · 1 idle · 3 notes · 2 warn · 0 fail degraded

The remaining warnings are terminal/search-related, not SQLite state failures.

Important detail: putting this only in .bashrc is not reliable for the VS Code extension WSL agent mode, because the extension launches WSL through non-interactive bash -lc. In my setup, .bashrc intentionally returns early for non-interactive shells.