Codex Code Review

Overview

To perform thorough, automated code reviews using the OpenAI Codex CLI agent, use this skill. Codex runs locally and can analyze code changes, identify issues, suggest improvements, and provide security/performance insights through non-interactive automation.

⚠️ CRITICAL: When reviewing code that involves dependency versions, latest releases, or current best practices, you MUST use the WebSearch tool to verify information before making any claims. Never assume version numbers or release status - always search first to avoid false positives. See the "Web Search Verification" section for details.

Prerequisites

Ensure Codex CLI is installed and authenticated:

# Install via npm
npm install -g @openai/codex

# Or via Homebrew (macOS)
brew install --cask codex

# Authenticate (recommended: ChatGPT account)
codex
# Follow authentication prompts

Decision Tree: Choosing Review Type

Code review request → What scope?
    ├─ Git changes (staged/unstaged) → Use: Git Diff Review
    │
    ├─ Pull Request → Use: PR Review Workflow
    │
    ├─ Specific files → Use: File Review
    │
    ├─ Entire directory/project → Use: Directory Review
    │
    └─ Special focus needed?
        ├─ Security concerns → Use: Security Audit
        ├─ Performance issues → Use: Performance Review
        └─ Architecture/Design → Use: Architecture Review

Headless Execution (Required)

When running codex for automated code reviews, you MUST use the --full-auto flag to grant all necessary permissions for headless operation. Without this flag, codex may hang waiting for user approval.

Always use --full-auto for non-interactive reviews:

# CORRECT: Full automation mode - grants all permissions automatically
codex --full-auto exec "Review the staged git changes..."

# WRONG: May hang waiting for approval in automated contexts
codex exec "Review the staged git changes..."

Why this matters:

• Codex requires approval for file reads, command execution, and other operations
• In headless/automated mode, there's no user to approve these actions
• --full-auto auto-approves all safe operations, enabling true automation

Alternative: Granular approval flags:

# Auto-approve specific operation types
codex --auto-approve-read --auto-approve-execute exec "..."

Quick Start

To perform a basic code review on staged changes:

codex --full-auto exec "Review the staged git changes. Analyze code quality, identify bugs, suggest improvements, and check for security issues. Provide a structured review with severity levels."

Review Workflows

1. Git Diff Review

To review uncommitted changes in the current repository:

Staged changes only:

codex --full-auto exec "Review all staged changes (git diff --cached). For each file:
1. Summarize what changed
2. Identify potential bugs or logic errors
3. Check for security vulnerabilities
4. Suggest code quality improvements
5. Rate severity: critical/high/medium/low

Format as a structured review report."

All uncommitted changes:

codex --full-auto exec "Review all uncommitted changes (git diff HEAD). Provide:
- Summary of changes per file
- Bug identification with line numbers
- Security concerns
- Code style issues
- Suggested fixes with code examples"

Changes between branches:

codex --full-auto exec "Review changes between main and current branch (git diff main...HEAD). Focus on:
1. Breaking changes
2. API compatibility
3. Test coverage gaps
4. Documentation needs"

2. PR Review Workflow

To review a GitHub Pull Request:

# First, fetch PR diff
gh pr diff <PR_NUMBER> > /tmp/pr_diff.txt

# Then review with codex (--full-auto for headless operation)
codex --full-auto exec "Review the code changes in /tmp/pr_diff.txt as a thorough PR reviewer. Provide:

## Summary
Brief description of what this PR accomplishes

## Code Review
For each file changed:
- Purpose of changes
- Potential issues (bugs, edge cases)
- Security considerations
- Performance implications

## Recommendations
- Required changes (blocking)
- Suggested improvements (non-blocking)
- Questions for the author

## Verdict
APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION"

3. File Review

To review specific files:

Single file:

codex --full-auto exec "Perform a comprehensive code review of src/utils/auth.ts. Analyze:
1. Code correctness and logic
2. Error handling completeness
3. Security vulnerabilities (OWASP Top 10)
4. Performance bottlenecks
5. Code maintainability
6. Test coverage recommendations"

Multiple files:

codex --full-auto exec "Review these files as a cohesive unit: src/api/handler.ts, src/api/middleware.ts, src/api/routes.ts. Focus on:
- Consistency across files
- Proper separation of concerns
- Error propagation
- Request validation"

4. Directory Review

To review an entire directory or project:

`

...