Codex CLI Code Review

Use the codex review command to get an AI-powered code review of the current changes.

Workflow

1. Check codex CLI availability

Run which codex to confirm it's installed. If not found, tell the user: "The codex CLI is not installed. Install it with npm install -g @openai/codex or see https://github.com/openai/codex"

2. Determine what to review

Pick the right flag based on context:

Staged changes only (default before a commit): codex review
All local changes (staged + unstaged + untracked): codex review --uncommitted
Changes against a branch: codex review --base <branch>
A specific commit: codex review --commit <sha>

If the user doesn't specify, check git diff --cached --stat first. If there are staged changes, review those. Otherwise fall back to --uncommitted.

3. Run the review

IMPORTANT: Use a 10-minute timeout (600000ms) for the Bash command — codex streams from the OpenAI API and large diffs can take several minutes to complete. The default 2-minute timeout will cause the stream to disconnect mid-review.

The prompt should describe what to focus on. If the user provided $ARGUMENTS, use that as the prompt. Otherwise use a sensible default like "review the changes for bugs, style issues, and potential improvements".

Command construction rules:

Staged changes (no flag): pass the prompt as a positional argument.
```
codex review "<prompt>"
```

With --base, --commit, or --uncommitted: the CLI does not allow a positional prompt argument alongside these flags. Pipe the prompt via stdin using - instead:

echo "<prompt>" | codex review --base <branch> -
echo "<prompt>" | codex review --uncommitted -
echo "<prompt>" | codex review --commit <sha> -

If the command fails due to environment issues (missing API key, network error, etc.), try these in order:

Check if OPENAI_API_KEY is set
Try running with --config model="gpt-5.2" as a fallback model
If still failing, report the error and skip the review

4. Save the review output

Save the full codex review output to .codex-review-output.md in the repository root.

5. Handle the review output

No issues found: Report that the review passed clean and proceed.
Minor suggestions: Summarize them for the user. These are informational — the user can decide whether to act on them.
Critical issues (bugs, security vulnerabilities, logic errors): Summarize the critical findings clearly. Ask the user whether they want to fix these before proceeding. If yes, make the fixes but do NOT commit — present the changes for human review first.

6. Environment troubleshooting

The codex CLI depends on:

Node.js runtime
OPENAI_API_KEY environment variable
Network access to OpenAI API

If running through asdf/nvm, the shim path may need to be resolved. Try $(which codex) or the full path if the shim doesn't work in the current shell context.