feat: add codex-review plugin for automated code review v1.0.0

.claude-plugin/marketplace.json

@@ -65,6 +65,16 @@
       "author": {
         "name": "vnz"
       }
+    },
+    {
+      "name": "codex-review",
+      "description": "AI-powered code review in Claude Code using the Codex CLI",
+      "version": "2.0.0",
+      "source": "./plugins/codex-review",
+      "category": "development",
+      "author": {
+        "name": "vnz"
+      }
     }
   ]
 }

README.md

@@ -26,6 +26,7 @@ Personal Claude Code plugin marketplace by vnz.
 | `bash-ls` | Bash language server for code intelligence, diagnostics, and formatting in shell scripts |
 | `yaml-ls` | YAML language server for code intelligence (go-to-definition, find-references, hover, diagnostics) |
 | `dependabot` | Check for dependency updates using Dependabot CLI with auto-detection of package managers |
+| `codex-review` | Automated code review with Codex CLI, auto-detection, and iterative fix-and-review loop |
 
 ## Usage
 
@@ -36,6 +37,7 @@ After adding the marketplace, install any plugin:
 /plugin install bash-ls@cc-plugins-vnz
 /plugin install yaml-ls@cc-plugins-vnz
 /plugin install dependabot@cc-plugins-vnz
+/plugin install codex-review@cc-plugins-vnz
 ```
 
 ## Development

plugins/codex-review/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "codex-review",
+  "version": "2.0.0",
+  "description": "AI-powered code review in Claude Code using the Codex CLI",
+  "license": "MIT",
+  "author": {
+    "name": "vnz"
+  },
+  "repository": "https://github.com/vnz/cc-plugins",
+  "keywords": ["code-review", "codex", "review", "quality", "ai"]
+}

plugins/codex-review/README.md

@@ -0,0 +1,144 @@
+# codex-review
+
+AI-powered code review plugin for Claude Code using the [Codex CLI](https://github.com/openai/codex). Provides a `/codex-review:review` command, a code-review skill for autonomous workflows, and a specialized review agent.
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Auto-detection** | Automatically selects `--uncommitted`, `--base`, or `--commit` mode |
+| **Fix-and-review loop** | Fixes findings and re-reviews until clean (max 4 cycles) |
+| **Anti-loop safety** | Three independent guards prevent runaway loops |
+| **Review agent** | Specialized subagent for thorough, autonomous code analysis |
+| **Silent fallback** | Does nothing if codex is not installed |
+
+## Prerequisites
+
+- [codex](https://github.com/openai/codex) CLI in your PATH
+- [gh](https://cli.github.com/) CLI (for PR base branch detection)
+
+## Installation
+
+```bash
+# Add marketplace
+/plugin marketplace add vnz/cc-plugins
+
+# Install plugin
+/plugin install codex-review@cc-plugins-vnz
+```
+
+## Usage
+
+### Command
+
+```bash
+# Auto-detect mode (most common)
+/codex-review:review
+
+# Review uncommitted changes only
+/codex-review:review uncommitted
+
+# Review against a specific branch
+/codex-review:review --base main
+
+# Review a specific commit
+/codex-review:review --commit abc1234
+```
+
+### Mode Detection
+
+The command automatically determines the right review strategy:
+
+1. If `--base <branch>` is passed, review the diff against that branch
+2. If the current branch has an open PR, review the full PR diff against its base
+3. Otherwise, review all uncommitted changes
+
+### Skill
+
+The code-review skill triggers when:
+
+- You ask Claude to review code
+- You ask about code quality, bugs, or security
+- You request implementation + review in one go
+
+### Agent
+
+The code-reviewer agent can be used as a subagent for thorough, focused review:
+
+```
+Use the code-reviewer agent to review these changes
+```
+
+## How the Fix Loop Works
+
+```
+┌─────────────────────┐
+│   Run codex review   │
+└──────────┬──────────┘
+           │
+     ┌─────▼─────┐
+     │ Findings?  │──── No ──→ Report clean ✓
+     └─────┬──────┘
+           │ Yes
+     ┌─────▼──────────┐
+     │ Fix actionable  │
+     │ Skip false pos.  │
+     └─────┬──────────┘
+           │
+     ┌─────▼──────────┐
+     │ Stop guards:    │
+     │ • cycle >= 4    │──── Any met ──→ Report & stop
+     │ • no progress   │
+     │ • no changes    │
+     └─────┬──────────┘
+           │ None met
+           └──→ Re-run review ↑
+```
+
+## Anti-Loop Safety
+
+| Guard | Condition | Rationale |
+|-------|-----------|-----------|
+| **Max cycles** | Cycle count reaches 4 | Hard cap prevents runaway loops |
+| **No progress** | All remaining findings were dismissed or already fixed | No new actionable findings to address |
+| **No changes** | `git diff --stat` empty after fixes | All findings were dismissed or already fixed |
+
+Any **one** of these triggers a stop.
+
+## Plugin Structure
+
+```
+plugins/codex-review/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   └── review.md              # /codex-review:review command
+├── skills/
+│   └── code-review/
+│       └── SKILL.md           # When/how to review, autonomous workflow
+├── agents/
+│   └── code-reviewer.md       # Specialized review subagent
+└── README.md
+```
+
+## Troubleshooting
+
+### Command not visible
+Run `/help` and look for `codex-review:review`. If missing, reinstall the plugin and restart Claude Code.
+
+### Codex not found
+The command silently exits if `codex` is not in your PATH. Install it:
+```bash
+npm install -g @openai/codex
+```
+
+### No PR detected
+If you expect `--base` mode but get `--uncommitted`, ensure:
+1. You've pushed the branch to the remote
+2. A PR is open (create one with `gh pr create`)
+3. The `gh` CLI is authenticated
+
+### Loop stops early
+Check which guard triggered in the final report. Common causes:
+- **No changes**: All findings were false positives — this is expected
+- **No progress**: Fixes introduced new issues — review the changes manually

plugins/codex-review/agents/code-reviewer.md

@@ -0,0 +1,94 @@
+---
+name: code-reviewer
+description: Specialized Codex code review agent that performs thorough analysis of code changes
+model: inherit
+color: green
+---
+
+# Codex Code Review Agent
+
+A specialized agent that leverages the Codex CLI to provide comprehensive analysis of your code changes.
+
+## Capabilities
+
+This agent specializes in:
+
+1. **Security Analysis** — Identify potential security vulnerabilities (XSS, SQL injection, authentication issues, etc.)
+2. **Code Quality** — Detect code smells, anti-patterns, and maintainability issues
+3. **Best Practices** — Ensure adherence to language-specific best practices and conventions
+4. **Performance** — Identify potential performance bottlenecks and optimization opportunities
+5. **Bug Detection** — Find potential bugs, edge cases, and error handling issues
+
+## When to Use
+
+Use this agent when you need:
+
+- A thorough review before merging a PR
+- Security-focused code analysis
+- Performance optimization suggestions
+- Best practice compliance checking
+- Code quality assessment
+
+## Prerequisites
+
+Codex CLI must be installed:
+
+```bash
+npm install -g @openai/codex
+```
+
+## Workflow
+
+1. **Gather Context**
+   - Identify changed files and their scope
+   - Understand the type of changes (feature, bugfix, refactor)
+   - Check for related configuration files
+
+2. **Run Codex Review**
+   - Execute `codex review` to get structured review output
+   - Parse and categorize findings by severity and type
+
+3. **Analyze Findings**
+   - Prioritize critical security issues
+   - Group related issues by file and functionality
+   - Identify patterns across multiple files
+
+4. **Provide Recommendations**
+   - Offer specific code fixes where applicable
+   - Suggest architectural improvements if needed
+   - Highlight positive aspects of the code
+
+5. **Interactive Resolution**
+   - Apply fixes for clearly actionable findings
+   - Explain complex issues in detail
+   - Re-run review to verify fixes resolved the findings
+
+## Review Categories
+
+### Critical (Must Fix)
+
+- Security vulnerabilities
+- Data exposure risks
+- Authentication/authorization flaws
+- Injection vulnerabilities
+
+### High Priority
+
+- Bug-prone code patterns
+- Missing error handling
+- Resource leaks
+- Race conditions
+
+### Medium Priority
+
+- Code duplication
+- Complex/hard-to-maintain code
+- Missing tests
+- Documentation gaps
+
+### Low Priority (Suggestions)
+
+- Style improvements
+- Minor optimizations
+- Naming conventions
+- Code organization

plugins/codex-review/commands/review.md

@@ -0,0 +1,65 @@
+---
+description: Run codex code review on your changes
+argument-hint: [type] [--base <branch>]
+allowed-tools: Bash(codex:*, git:*, gh:*), Read, Grep, Glob
+---
+
+# Codex Code Review
+
+Run an automated code review using the Codex CLI.
+
+## Context
+
+- Current directory: !`pwd`
+- Git repo: !`git rev-parse --is-inside-work-tree 2>/dev/null && echo "Yes" || echo "No"`
+- Branch: !`git branch --show-current 2>/dev/null || echo "detached HEAD"`
+- Has changes: !`git status --porcelain 2>/dev/null | head -1 | grep -q . && echo "Yes" || echo "No"`
+
+## Instructions
+
+Review code based on: **$ARGUMENTS**
+
+### Prerequisites Check
+
+**Skip this check if you already verified codex earlier in this session.**
+
+```bash
+command -v codex >/dev/null 2>&1 && echo "codex found" || echo "codex not found"
+```
+
+**If not found**, tell user:
+> Codex CLI is not installed. Install it:
+>
+> ```bash
+> npm install -g @openai/codex
+> ```
+>
+> Then restart your shell and try again.
+
+### Detect Review Mode
+
+Determine which mode to use from `$ARGUMENTS`:
+
+1. If `--base <branch>` is specified, use: `codex review --base <branch>` (pass the ref as-is — the user may specify `origin/main`, `upstream/dev`, or a local branch)
+2. If type is `committed`, use: `codex review` (no flags — reviews committed changes by default)
+3. If type is `uncommitted`, use: `codex review --uncommitted`
+4. If `--commit <SHA>` is specified, use: `codex review --commit <SHA>`
+5. Default (no arguments): auto-detect:
+   - Check for open PR → `codex review --base origin/<base>`
+   - Otherwise → `codex review --uncommitted`
+
+### Run Review
+
+Run the detected command as a **background task** (`run_in_background: true`). Wait for it to complete.
+
+### Present Results
+
+Group findings by severity:
+
+1. **P1 — Critical**: Security, bugs, data loss risks
+2. **P2 — Important**: Error handling gaps, missing validation
+3. **P3 — Minor**: Style, naming, minor simplifications
+
+If no findings, report that the review is clean.
+
+Offer to fix actionable findings if any are present.