bootstrap/tools/codex/README.md

Codex CLI Review Scripts

AI-powered code review and security review scripts using OpenAI's Codex CLI.

These scripts provide independent code analysis separate from Claude sessions, giving you a second AI perspective on code changes to catch issues that might be missed.

Prerequisites

# Install Codex CLI
npm i -g @openai/codex

# Verify installation
codex --version

# Authenticate (first run)
codex  # Will prompt for ChatGPT account or API key

# Verify jq is installed (for JSON processing)
jq --version

Scripts

codex-code-review.sh

General code quality review focusing on:

• Correctness — logic errors, edge cases, error handling
• Code Quality — complexity, duplication, naming, dead code
• Testing — coverage, test quality
• Performance — N+1 queries, blocking operations, resource cleanup
• Dependencies — deprecated packages
• Documentation — comments, public API docs

Output: Structured JSON with findings categorized as blocker, should-fix, or suggestion.

codex-security-review.sh

Security vulnerability review focusing on:

• OWASP Top 10 — injection, broken auth, XSS, CSRF, SSRF, etc.
• Secrets Detection — hardcoded credentials, API keys, tokens
• Injection Flaws — SQL, NoSQL, OS command, LDAP
• Auth/Authz Gaps — missing checks, privilege escalation, IDOR
• Data Exposure — logging sensitive data, information disclosure
• Supply Chain — vulnerable dependencies, typosquatting

Output: Structured JSON with findings categorized as critical, high, medium, or low with CWE IDs and OWASP categories.

Usage

Review Uncommitted Changes

# Code review
~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted

# Security review
~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted

Review a Pull Request

# Review and post findings as a PR comment
~/.config/mosaic/tools/codex/codex-code-review.sh -n 42

# Security review and post to PR
~/.config/mosaic/tools/codex/codex-security-review.sh -n 42

Review Against Base Branch

# Code review changes vs main
~/.config/mosaic/tools/codex/codex-code-review.sh -b main

# Security review changes vs develop
~/.config/mosaic/tools/codex/codex-security-review.sh -b develop

Review a Specific Commit

~/.config/mosaic/tools/codex/codex-code-review.sh -c abc123f
~/.config/mosaic/tools/codex/codex-security-review.sh -c abc123f

Save Results to File

# Save JSON output
~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted -o review-results.json
~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted -o security-results.json

Options

Both scripts support the same options:

Option	Description
-n, --pr <number>	PR number (auto-enables posting to PR)
-b, --base <branch>	Base branch to diff against (default: main)
-c, --commit <sha>	Review a specific commit
-o, --output <path>	Write JSON results to file
--post-to-pr	Post findings as PR comment (requires -n)
--uncommitted	Review uncommitted changes (staged + unstaged + untracked)
-h, --help	Show help

Woodpecker CI Integration

Automated PR reviews in CI pipelines.

Setup

1. Copy the pipeline template to your repo:

   cp ~/.config/mosaic/tools/codex/woodpecker/codex-review.yml your-repo/.woodpecker/
   

2. Copy the schemas directory:

   cp -r ~/.config/mosaic/tools/codex/schemas your-repo/.woodpecker/
   

3. Add Codex API key to Woodpecker:

   • Go to your repo in Woodpecker CI
   • Settings → Secrets
   • Add secret: codex_api_key with your OpenAI API key

4. Commit and push:

   cd your-repo
   git add .woodpecker/
   git commit -m "feat: Add Codex AI review pipeline"
   git push
   

Pipeline Behavior

• Triggers on: Pull requests
• Runs: Code review + Security review in parallel
• Fails if:
  • Code review finds blockers
  • Security review finds critical or high severity issues
• Outputs: Structured JSON results in CI logs

Output Format

Code Review JSON

{
  "summary": "Overall assessment...",
  "verdict": "approve|request-changes|comment",
  "confidence": 0.85,
  "findings": [
    {
      "severity": "blocker",
      "title": "SQL injection vulnerability",
      "file": "src/api/users.ts",
      "line_start": 42,
      "line_end": 45,
      "description": "User input directly interpolated into SQL query",
      "suggestion": "Use parameterized queries"
    }
  ],
  "stats": {
    "files_reviewed": 5,
    "blockers": 1,
    "should_fix": 3,
    "suggestions": 8
  }
}

Security Review JSON

{
  "summary": "Security assessment...",
  "risk_level": "high",
  "confidence": 0.90,
  "findings": [
    {
      "severity": "high",
      "title": "Hardcoded API key",
      "file": "src/config.ts",
      "line_start": 10,
      "description": "API key hardcoded in source",
      "cwe_id": "CWE-798",
      "owasp_category": "A02:2021-Cryptographic Failures",
      "remediation": "Move to environment variables or secrets manager"
    }
  ],
  "stats": {
    "files_reviewed": 5,
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 3
  }
}

Platform Support

Works with both GitHub and Gitea via the shared ~/.config/mosaic/tools/git/ infrastructure:

• Auto-detects platform from git remote
• Posts PR comments using gh (GitHub) or tea (Gitea)
• Unified interface across both platforms

Architecture

codex-code-review.sh
codex-security-review.sh
    ↓
common.sh
    ↓ sources
../git/detect-platform.sh  (platform detection)
../git/pr-review.sh        (post PR comments)
    ↓ uses
gh (GitHub) or tea (Gitea)

Troubleshooting

"codex: command not found"

npm i -g @openai/codex

"jq: command not found"

# Arch Linux
sudo pacman -S jq

# Debian/Ubuntu
sudo apt install jq

"Error: Not inside a git repository"

Run the script from inside a git repository.

"No changes found to review"

The specified mode (--uncommitted, --base, etc.) found no changes to review.

"Codex produced no output"

Check your Codex API key and authentication:

codex  # Re-authenticate if needed

Model Configuration

By default, scripts use the model configured in ~/.codex/config.toml:

• Model: gpt-5.3-codex (recommended for code review)
• Reasoning effort: high

For best results, use gpt-5.2-codex or newer for strongest review accuracy.

See Also

• ~/.config/mosaic/guides/CODE-REVIEW.md — Manual code review checklist
• ~/.config/mosaic/tools/git/ — Git helper scripts (issue/PR management)
• OpenAI Codex CLI docs: https://developers.openai.com/codex/cli/