OpenAI Codex CLI

Use OpenAI's Codex command-line tool as a Cerevisor provider, ChatGPT subscription auth, sandbox modes, and the limits to know about.

The Codex CLI provider runs each agent by spawning codex exec --json as a subprocess. OpenAI's Codex owns the agentic loop, sandboxing, and auth, Cerevisor handles wave orchestration, dependency tracking, and inter-agent handoff.

The main reason to use it: you have a ChatGPT Plus or Pro subscription and don't want to pay per-token for the same model when you're already paying monthly.

Prerequisites

  • Node.js (any recent LTS).
  • Codex CLI installed: npm install -g @openai/codex.
  • A ChatGPT Plus / Pro subscription (or an OpenAI API key; both auth modes are supported, but the subscription path is the typical case).

Setup wizard

  1. Settings → Providers → + Add provider → Codex CLI.

The wizard runs six steps:

1. Detect

Cerevisor runs codex --version to confirm Codex is installed and reachable. On Windows, it auto-resolves the .cmd shim that npm install -g creates.

2. Auth status

Runs codex login status to check whether you're already signed in. If you are, skip ahead. If not:

3. Device auth

Click Start device auth. Cerevisor invokes codex login --device-auth. A URL and code appear; copy the code and open the URL in a browser, sign in to ChatGPT, paste the code. The wizard polls codex login status every 2 seconds and advances when sign-in completes.

4. Keyring config (optional)

On supported platforms, the wizard offers to write Codex's auth into your OS keyring instead of the plain text file. Recommended.

5. Smoke test

Cerevisor runs codex exec --json with a trivial prompt to confirm everything works end-to-end. The smoke test result is shown.

6. Save

The provider becomes available.

What Codex CLI runs

When an agent uses the Codex CLI provider, Cerevisor invokes:

codex exec --json \
  --ephemeral \
  --skip-git-repo-check \
  --cd <project-folder> \
  -c sandbox_mode=<read-only|workspace-write|danger-full-access> \
  -c approval_policy=<untrusted|on-failure|on-request|never> \
  --output-last-message <temp-file> \
  -

The prompt is piped via stdin (the - positional). --ephemeral disables Codex's session-rollout writer (so two Cerevisor agents using Codex don't conflict).

Sandbox modes

Cerevisor translates your workflow's permissions to Codex's sandbox_mode:

Cerevisor permissions Codex sandbox_mode
All filesystem set to Allow + execution set to Allow danger-full-access
Workspace writes Allow, outside workspace blocked workspace-write
Everything read-only read-only

Approval policies

Cerevisor derives approval_policy from the same WorkflowPermissions (file write + bash execution + web access), not from a single trust-profile selector. The common patterns:

Cerevisor permissions Codex approval_policy
File write + bash + web all Allow never
File write Allow, bash blocked or web blocked on-failure
Most categories Ask on-request
Read-only across the board untrusted

When in doubt, set the workflow permissions you actually want and let Cerevisor compute the matching Codex flags.

Known v1 limitations

These are the trade-offs of using Codex as your runner, known limitations, not bugs:

  • Per-tool permission prompts don't interpose. Cerevisor's PermissionModal can't intercept individual tool calls inside Codex's subprocess. Sandbox + approval policy are set up-front.
  • Mid-run conversation resume is not supported. Codex's exec mode is one-shot per prompt. So the contract-retry and verifier-retry paths Cerevisor uses for other providers are disabled for Codex agents: the harness emits agent_verifier_skipped with reason codex-cli-no-resume.
  • Background features can't use Codex. The chat builder, run retrospectives, memory crystallization: anything that does .chat(), require an Anthropic or OpenAI-compatible provider. Configure one separately for background use.
  • MCP tools added in Cerevisor don't reach Codex. Codex has its own tool catalog; Cerevisor doesn't inject MCP tools into the subprocess.
  • Cost is reported as $0.00. Subscription billing: Cerevisor has no way to compute per-call cost. The analytics view classifies these sessions as "subscription" so they're distinguishable from per-token runs.

Switching ChatGPT plans

The Codex CLI is tied to your ChatGPT account. If you upgrade or downgrade your plan, Codex picks up the change automatically, no Cerevisor action needed.

Windows note

npm install -g @openai/codex installs as codex.cmd on Windows. Cerevisor auto-resolves the .cmd path so child_process.spawn('codex', ...) works. If the wizard reports "Codex not found" but codex --version works in your terminal, restart Cerevisor, PATH is read at launch.

macOS note

If you launched Cerevisor from Finder (not Terminal), macOS strips PATH to the system defaults, so even though which codex works in your terminal, the launched app might not see it. Cerevisor uses fix-path at startup on macOS to repair PATH for the lifetime of the process, so this should be transparent.

Back to docs