Installing Codex (Prerequisites)

CodeMantis can use OpenAI Codex as a first-class coding agent alongside (or instead of) Claude Code. This page covers Codex setup. You only need one of the two CLIs installed to start using CodeMantis — both is better, but either alone is enough.

What is Codex?

Codex is OpenAI's command-line coding agent. It reads your files, writes code, and runs commands under a sandbox-and-approval-policy model. CodeMantis wraps Codex the same way it wraps Claude Code — three-panel layout, activity feed, file viewer, SpecWriter, Self-Drive — with a Codex Policy Pill in the input toolbar that replaces the Mode Selector for Codex sessions.

Subscription Requirements

Codex authenticates against your existing OpenAI subscription via OAuth:

• ChatGPT Plus ($20/month) — sufficient for moderate Codex usage.
• ChatGPT Pro — higher quotas; recommended for heavier sessions.
• ChatGPT Business — for team accounts with admin-managed access.

No separate OpenAI API key is required. Codex draws against your ChatGPT subscription pool the same way Claude Code (in interactive mode) draws against your Claude Pro or Max pool.

Installation

Make sure you have Node.js 18 or later installed, then run one of:

npm install -g @openai/codex

Or, if you prefer Homebrew:

brew install codex

Either command installs the codex binary globally on your system.

Sign In

After installation, authenticate with your OpenAI account:

codex login

A browser window will open for OAuth authorization. Once complete, credentials are persisted to ~/.codex/auth.json and the CLI will confirm that you are signed in.

Verify the Installation

Run the following to confirm Codex is on your PATH:

which codex

You should see a path such as /usr/local/bin/codex or /opt/homebrew/bin/codex. If it prints nothing, the CLI is not on your system PATH.

Fixing Common PATH Issues

On macOS with zsh (the default shell), the codex binary may not be found if your npm global directory or Homebrew prefix is not in your PATH.

Option 1: Add npm global bin to your PATH

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Option 2: Use a custom npm global directory

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
npm install -g @openai/codex

Option 3: Homebrew path on Apple Silicon

echo 'export PATH="/opt/homebrew/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

After any fix, run which codex again to confirm.

Next Steps

Once codex is installed and authenticated, open CodeMantis and it will detect the CLI automatically. The Welcome Screen prerequisites checklist shows a green check next to OpenAI Codex CLI and Codex authentication.

• Choosing your coding agent — When to pick Claude, when to pick Codex, and how per-task routing works.
• Per-task agent routing — Route main chat, SpecWriter, Help, and the Assistant panel to different agents (v1.5.0).
• Codex not found — Troubleshoot detection issues.

For the full Codex documentation, visit the official OpenAI Codex docs.