# 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

```bash
# 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

```bash
# 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

```bash
# 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
```

PR mode resolves the provider's PR diff rather than relying on the caller's checked-out branch. On Gitea, it fetches the base and `refs/pull/<number>/head` refs and diffs those explicit refs. If the refs cannot be fetched or the resulting diff is empty, the command exits nonzero before Codex runs or a review is posted.

### Review Against Base Branch

```bash
# 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

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

### Save Results to File

```bash
# 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:**

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

2. **Copy the schemas directory:**

   ```bash
   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:**
   ```bash
   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

```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

```json
{
  "summary": "Security assessment...",
  "risk_level": "high",
  "confidence": 0.9,
  "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"

```bash
npm i -g @openai/codex
```

### "jq: command not found"

```bash
# 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 non-PR mode (`--uncommitted`, `--base`, etc.) found no changes to review. PR mode instead fails closed with an actionable error when it cannot construct a non-empty provider diff; verify the PR number, remote, provider login, and ref access before retrying.

### "Codex produced no output"

Check your Codex API key and authentication:

```bash
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/
