Troubleshooting

Install fails or cannot find codex-windows

Confirm Node.js 22 is active and npm’s global bin folder is on your PATH.

• Re-run nvm use 22 and check where node.
• Ensure %AppData%\npm (or the folder reported by npm bin -g) is on your PATH.
• Reinstall if needed:

  npm uninstall -g @cpjet64/codex-windows
  npm i -g @cpjet64/codex-windows@latest

Execution policy blocks the CLI

If PowerShell refuses to launch Codex because of script restrictions, adjust the policy for the current user:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Restart PowerShell afterwards so the policy takes effect.

Antivirus flags the binary

Some antivirus suites quarantine freshly installed Node binaries. Add the npm global directory to your allow list and reinstall. The default path is %AppData%\npm.

VS Build Tools commands do not run

Codex automatically inherits MSVC environment variables if Visual Studio Build Tools or Visual Studio are installed. No developer PowerShell prompt is required.

• Make sure you installed the “Desktop development with C++” workload.
• Open a fresh PowerShell window and run codex-windows --version to confirm the environment is detected.

Sandbox or seatbelt issues

The fork respects the same environment variables as upstream. If you see errors mentioning CODEX_SANDBOX or CODEX_SANDBOX_NETWORK_DISABLED, review the sandbox documentation and adjust the environment before launching Codex.

Resetting local state

If configuration files get into a bad state, remove the Codex cache and start over:

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\codex" -ErrorAction Ignore
Remove-Item -Recurse -Force "$env:USERPROFILE\.codex" -ErrorAction Ignore

Reinstall afterwards with the standard npm command.

Gathering logs for issue reports

Include the following when you open an issue:

• Output of codex-windows --version.
• Node version (node -v) and nvm version.
• Relevant CLI output or stack traces.
• Whether you are behind a corporate proxy, using antivirus, or running inside WSL/VM.