codex-preflight

Codex Preflight Check

Run a preflight check to verify Codex is working and discover which models are available.

Workflow

Step 1: Run the preflight script

bash "${CLAUDE_PLUGIN_ROOT}/scripts/codex-preflight.sh"

Parse the JSON output from stdout. The script also prints a human-readable summary to stderr.

Step 2: Display results

Present the results in a clear, readable format:

## Codex Preflight Results

**Status**: {status}
**Codex version**: {codex_version}
**Auth mode**: {auth_mode}
**Codex Cloud**: {codex_cloud}
**Default model**: {default_model}

The default is selected dynamically from the current Codex model catalog. The
preflight prefers the latest-marked general-purpose model, then the newest
version, and does not hardcode a model name or select review-only models.

### Available Models

| Model | Status |
|-------|--------|
| {model-name} | Available |

### Unavailable Models

| Model | Status |
|-------|--------|
| {model-name} | Unavailable |

### Options

- **Reasoning efforts**: {reasoning_efforts from preflight}
- **Sandbox levels**: read-only, workspace-write, danger-full-access

Step 3: Handle errors

Failures are reported in band: the script prints the same field set with "status": "error", a stable error_code, and empty models, and still exits 0. Switch on status, never on the exit code.

• If status is "error":

  • Display the error message prominently

  • Suggest the fix for its error_code (branch on the code, not the message text):

    error_code	Fix
    codex_not_found	npm install -g @openai/codex
    codex_not_authenticated	codex login
    codex_no_models_cache	Run any codex session once (e.g. codex exec 'say ok') to repopulate ~/.codex/models_cache.json

• If models is empty:
  • Warn: "No models are currently available"
  • Suggest: Check subscription status, then run any codex session once (e.g. codex exec 'say ok') to repopulate the model cache — codex login does not refresh the model list