BUG: Windows hapi codex fails when npm Codex CLI shim is first on PATH

[Pililink]

Windows: hapi codex fails when npm Codex CLI shim is first on PATH

Summary

On Windows, hapi codex fails when Codex CLI is installed globally via npm and the first codex entries on PATH are npm-generated shims:

<USER_HOME>\AppData\Roaming\npm\codex
<USER_HOME>\AppData\Roaming\npm\codex.cmd

The same setup works if the native Codex binary from the npm package is prepended to PATH.

Environment

• OS: Windows x64
• Shell: PowerShell 7.6.1
• hapi: 0.17.4
• Codex CLI: 0.130.0
• Codex install method: npm install -g @openai/codex@latest

Reproduction

npm install -g @openai/codex@latest
where.exe codex
codex --version
hapi codex

where.exe codex returns:

<USER_HOME>\AppData\Roaming\npm\codex
<USER_HOME>\AppData\Roaming\npm\codex.cmd

codex --version works:

codex-cli 0.130.0

But hapi codex fails:

The system cannot find the file specified.
[codex-local]: Local Codex process failed: Process exited with code: 1
Failed to execute: "<USER_HOME>\AppData\Roaming\npm\node_modules\@twsxtd\hapi\node_modules\@twsxtd\hapi-win32-x64\bin\hapi.exe" "codex"
Binary exited with status 1.

Workaround

Prepending the native Codex binary directory from the npm package to PATH makes hapi codex start successfully:

$codexExeDir = "$env:APPDATA\npm\node_modules\@openai\codex\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc\codex"
$codexPathDir = "$env:APPDATA\npm\node_modules\@openai\codex\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc\path"
$env:Path = "$codexExeDir;$codexPathDir;$env:Path"

where.exe codex
hapi codex

Then where.exe codex starts with:

<USER_HOME>\AppData\Roaming\npm\node_modules\@openai\codex\node_modules\@openai\codex-win32-x64\vendor\x86_64-pc-windows-msvc\codex\codex.exe

Suspected Cause

hapi codex appears to spawn codex by name. On Windows, when npm shims are first on PATH, this can resolve to the extensionless npm shim or codex.cmd rather than the native codex.exe.

This seems to break the local Codex launch path used by hapi, especially because hapi passes complex -c config values for MCP and session hooks.

A possible fix could be to prefer a native codex.exe on Windows when available, or provide an environment variable/config option to override the Codex binary path used by hapi.

[github-actions]

Thanks for the detailed report. I verified the local Codex launch path in the current codebase, and your suspected cause matches what HAPI does today.

hapi codex checks codex --version first, but the actual local session launch still spawns codex by command name. The launch path does not currently resolve a native codex.exe on Windows and I did not find a Codex equivalent of HAPI_CLAUDE_PATH.

So the workaround you listed, putting the native Codex binary directory before the npm shim on PATH, is consistent with the current implementation.

Relevant code:

• cli/src/commands/codex.ts:87 - local terminal launches call assertCodexLocalSupported() before starting Codex.
• cli/src/codex/utils/codexVersion.ts:57 - the version check runs codex --version via cross-spawn.
• cli/src/codex/codexLocal.ts:88 - local Codex launch calls spawnWithTerminalGuard().
• cli/src/codex/codexLocal.ts:89 - the command passed to the launcher is the literal codex.
• cli/src/utils/spawnWithAbort.ts:51 - the shared launcher uses cross-spawn with the provided command and args.
• cli/src/codex/codexLocal.test.ts:56 - existing test asserts local Codex launches without shell so -c config values remain argv elements.
• cli/src/claude/sdk/utils.ts:99 - Claude has an explicit HAPI_CLAUDE_PATH override; I did not find a matching Codex override.

Need more info:

• Does this fail only for local hapi codex, or also when starting Codex sessions through hapi runner from the web UI?

---

HAPI Bot