Skip to main content

​
Syntax

codex review [OPTIONS]

​
Description

The review command runs Codex in code review mode. You can review uncommitted changes, compare against a base branch, review a specific commit, or provide custom review instructions.
The review command runs non-interactively like codex exec. Use codex review --help for all available options.

​
Usage

​
Review Uncommitted Changes

codex review --uncommitted

​
Review Against Base Branch

Compare current branch with main: 
codex review --base main
codex review --base develop

​
Review Specific Commit

codex review --commit abc123
codex review --commit HEAD~1
With commit title for context: 
codex review --commit abc123 --commit-title "Add user authentication"

​
Custom Review Instructions

Provide specific review criteria: 
codex review "focus on security vulnerabilities"
codex review "check for performance issues"
codex review "ensure code follows project style guide"
From stdin: 
echo "review for accessibility issues" | codex review
codex review < review-checklist.txt

​
Options

​
Review Target

​
--uncommitted
boolean
Review uncommitted changes in the working directory.
​
--base
string
Review changes compared to a base branch (e.g., main, develop).
​
--commit
string
Review a specific commit by SHA or reference (e.g., abc123, HEAD~1).
​
--commit-title
string
Provide a commit title for context. Only valid with --commit.
​
PROMPT
string
Custom review instructions. Use - to read from stdin.

​
Output

​
-o, --output-last-message
path
Save the review report to a file.
​
--json
boolean
Output review events as JSON Lines.

​
Model & Execution

​
-m, --model
string
AI model to use for the review.
​
--color
string
Control colored output: auto, always, never.

​
Examples

​
Pre-Commit Review

# Review before committing
codex review --uncommitted

# Save review to file
codex review --uncommitted -o pre-commit-review.md

​
Pull Request Review

# Review changes in current branch vs main
codex review --base main

# Review with JSON output for CI
codex review --base main --json > pr-review.jsonl

​
Commit Review

# Review the last commit
codex review --commit HEAD

# Review a specific commit with context
codex review --commit abc123 --commit-title "Fix authentication bug"

# Review a range of commits
for commit in $(git log --format=%H -n 5); do
  codex review --commit $commit -o "review-$commit.md"
done

​
Focused Reviews

# Security review
codex review --uncommitted "focus on security vulnerabilities and input validation"

# Performance review
codex review --base main "identify performance bottlenecks and optimization opportunities"

# Code quality review
codex review <<EOF
Review for:
- Code duplication
- Proper error handling
- Test coverage
- Documentation completeness
EOF

​
CI/CD Integration

# GitHub Actions
name: Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Full history for base comparison
      
      - name: Review Changes
        run: |
          codex review --base ${{ github.base_ref }} --json > review.jsonl
          codex review --base ${{ github.base_ref }} -o review-report.md
      
      - name: Upload Review
        uses: actions/upload-artifact@v3
        with:
          name: code-review
          path: review-report.md

​
Pre-Commit Hook

#!/bin/bash
# .git/hooks/pre-commit

echo "Running Codex review on uncommitted changes..."

codex review --uncommitted -o /tmp/codex-review.txt

if [ $? -ne 0 ]; then
  echo "Review failed. See /tmp/codex-review.txt for details."
  exit 1
fi

echo "Review complete. See /tmp/codex-review.txt"

​
Different Models

# Use GPT-4.1 for thorough reviews
codex review --base main -m gpt-4.1

# Quick review with o4-mini
codex review --uncommitted -m o4-mini

​
Review Output

By default, Codex outputs the review to stderr. Use -o to save to a file: 
codex review --uncommitted -o review.md
With --json, events are emitted as JSON Lines: 
codex review --base main --json | jq -r 'select(.msg.type=="text") | .msg.content'

​
Exit Codes

  • 0 - Review completed successfully
  • 1 - Error occurred during review
The exit code indicates whether the review ran successfully, not whether the code passed review. Check the review content for findings.