Codex Not Found
What to do when CodeMantis cannot detect your OpenAI Codex CLI installation.
If the Welcome Screen shows "OpenAI Codex CLI — Not installed" but you've already installed Codex, the CLI is most likely on disk but not on the PATH that CodeMantis can see. This page covers the fixes in order.
Looking for Claude Code? See Claude Code Not Found instead.
Step 1: Confirm Codex Is Actually Installed
Open Terminal and run:
which codex- If it prints a path (e.g.
/usr/local/bin/codex,/opt/homebrew/bin/codex, or~/.npm-global/bin/codex), Codex is installed and the issue is PATH visibility for the CodeMantis app. Continue to Step 2. - If it prints nothing, Codex is not installed. Install it with
npm install -g @openai/codexorbrew install codex, then come back. See Installing Codex for the full setup walkthrough.
Step 2: Re-check from CodeMantis
On the Welcome Screen, click the Re-check button in the Requirements card. CodeMantis re-runs detection. Sometimes a fresh shell environment or a recent install hasn't been picked up yet.
If the Welcome Screen is no longer visible (you've dismissed it), open Settings › Agents and look at the Codex row. The install + auth badges refresh on tab open.
Step 3: Locate Codex Manually
If detection still fails, the binary is in a non-standard location (common with nvm, volta, fnm, or Homebrew on Apple Silicon with a custom prefix).
On the Welcome Screen, click "Locate Codex" in the yellow warning banner. A file picker opens — navigate to the path which codex printed in Step 1 and select the codex binary. CodeMantis persists this as a binary override.
Step 4: Authenticate Codex
If the install badge is green but the authentication badge is yellow ("Sign-in required"), run:
codex loginA browser window will open for OAuth authorization. Once complete, credentials are persisted to ~/.codex/auth.json. Click Re-check in CodeMantis to refresh.
Common Causes
nvm/volta/fnmshells — npm globals are installed under the active Node version directory, which isn't on the system PATH. Either use Locate Codex or add the version's bin directory to your shell config.- Homebrew on Apple Silicon —
/opt/homebrew/binmay not be in PATH on a fresh setup. Addexport PATH="/opt/homebrew/bin:$PATH"to~/.zshrc. pnpm/yarnglobal — these use their own global directories. Find the bin path withpnpm bin -goryarn global bin.- Just-installed in a different terminal — quit and relaunch CodeMantis so it inherits the updated environment.
Still Stuck?
You don't need Codex to use CodeMantis — if Claude Code is installed and authenticated, the app works exactly as it did before Codex support shipped. Codex is a second-agent option, not a requirement.
If you want help getting Codex working, file an issue at github.com/codemantis-dev/codemantis and include:
- The output of
which codex - The output of
codex --version - Which Node version manager (if any) you use
- The contents of the yellow warning banner on the Welcome Screen