Codex Review Checkpoint

Code review checkpoint that runs codex review on the current worktree.

Note: The gate-runner script runs this automatically for issues with gate:codex-review label. This skill documents the process for manual use.

Quick Start

Review uncommitted changes

codex review --uncommitted --title "My Review"

Review branch changes against main

codex review --base main --title "Feature Review"

Review a specific commit

codex review --commit abc123

What This Skill Does

• Determines what to review (uncommitted changes vs branch diff)

• Runs codex review (non-interactive, exits on completion)

• Parses results into structured format

• Writes result to checkpoint file

Workflow

Step 1: Determine Review Scope

Check for uncommitted changes

git status --porcelain

Check for branch diff

git diff --quiet main...HEAD && echo "No branch changes" || echo "Has branch changes"

Step 2: Run Codex Review

For uncommitted changes

codex review --uncommitted --title "Checkpoint Review"

For branch diff against main

codex review --base main --title "Checkpoint Review"

Codex review:

• Runs non-interactively (no terminal interaction needed)

• Outputs structured findings with severity levels (P1, P2, P3)

• Exits with appropriate status

Step 3: Parse and Write Result

After reviewing, create a structured result:

{ "checkpoint": "codex-review", "timestamp": "2026-01-19T12:00:00Z", "passed": true, "issues": [], "summary": "No critical issues found" }

Result Fields:

• passed : true if no P1/P2 issues found

• issues : array of {severity, message, file?, line?}

• summary : brief human-readable summary

Step 4: Write Checkpoint File

mkdir -p .checkpoints cat > .checkpoints/codex-review.json << 'EOF' { "checkpoint": "codex-review", "timestamp": "...", "passed": true, "issues": [], "summary": "..." } EOF

Decision Criteria

Pass if:

• No P1 or P2 issues found

• No security vulnerabilities detected

• No obvious bugs or logic errors

Fail if:

• P1/P2 issues found

• Security issues found

• Critical bugs detected

Example Output

$ codex review --uncommitted --title "Feature Review" OpenAI Codex v0.87.0 (research preview)

workdir: /home/user/project model: gpt-5.2 ...

[P2] Guard against missing script before execution — path/to/file.sh:45 Description of the issue...

[P3] Consider adding error handling — path/to/other.ts:120 Suggestion details...

Automated Usage

The gate-runner.sh script runs codex review automatically:

./plugins/conductor/scripts/gate-runner.sh --issue ISSUE-ID --worktree /path/to/worktree

This:

• Checks issue labels for gate:codex-review

• Runs codex review directly (no terminal spawn needed)

• Writes checkpoint to .checkpoints/codex-review.json

• Returns pass/fail status