From 7bd5f14a9130bbb85d9bd370bd40d3fdd846b900 Mon Sep 17 00:00:00 2001 From: vnz <1267662+vnz@users.noreply.github.com> Date: Fri, 20 Mar 2026 20:17:46 +0100 Subject: [PATCH 1/6] feat: add codex-review plugin for automated code review v1.0.0 First command-based plugin in the marketplace. Provides /codex-review slash command with auto-detection of review mode (--uncommitted, --base, --commit) and iterative fix-and-review loop with three anti-loop safety guards. Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 10 ++ README.md | 2 + .../codex-review/.claude-plugin/plugin.json | 11 ++ plugins/codex-review/README.md | 104 ++++++++++++++++++ plugins/codex-review/commands/codex-review.md | 60 ++++++++++ .../skills/review-workflow/SKILL.md | 46 ++++++++ 6 files changed, 233 insertions(+) create mode 100644 plugins/codex-review/.claude-plugin/plugin.json create mode 100644 plugins/codex-review/README.md create mode 100644 plugins/codex-review/commands/codex-review.md create mode 100644 plugins/codex-review/skills/review-workflow/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 890c4ab..863ed22 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -65,6 +65,16 @@ "author": { "name": "vnz" } + }, + { + "name": "codex-review", + "description": "Automated code review using Codex CLI with autonomous fix-review cycles", + "version": "2.0.0", + "source": "./plugins/codex-review", + "category": "development", + "author": { + "name": "vnz" + } } ] } diff --git a/README.md b/README.md index c3ec631..10ea34c 100644 --- a/README.md +++ b/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 diff --git a/plugins/codex-review/.claude-plugin/plugin.json b/plugins/codex-review/.claude-plugin/plugin.json new file mode 100644 index 0000000..426bb69 --- /dev/null +++ b/plugins/codex-review/.claude-plugin/plugin.json @@ -0,0 +1,11 @@ +{ + "name": "codex-review", + "version": "1.0.0", + "description": "Automated code review using OpenAI Codex CLI with auto-detection of review mode and iterative fix-and-review loop", + "license": "MIT", + "author": { + "name": "vnz" + }, + "repository": "https://github.com/vnz/cc-plugins", + "keywords": ["code-review", "codex", "review", "quality", "ci"] +} diff --git a/plugins/codex-review/README.md b/plugins/codex-review/README.md new file mode 100644 index 0000000..6f3d980 --- /dev/null +++ b/plugins/codex-review/README.md @@ -0,0 +1,104 @@ +# codex-review + +Automated code review plugin for Claude Code using the OpenAI Codex CLI. Provides a `/codex-review` slash command with automatic mode detection and an iterative fix-and-review loop. + +## Features + +| Feature | Description | +|---------|-------------| +| **Auto-detection** | Automatically selects `--uncommitted`, `--base`, or `--commit` mode | +| **Fix-and-review loop** | Fixes findings and re-reviews until clean | +| **Anti-loop safety** | Three independent guards prevent runaway loops | +| **Background execution** | Reviews run as background tasks | +| **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 + +```bash +# Auto-detect mode (most common) +/codex-review + +# Review a specific commit +/codex-review --commit abc1234 +``` + +### Mode Detection + +The command automatically determines the right review strategy: + +1. If `--commit ` is passed, review that commit +2. If the current branch has an open PR, review the full PR diff against its base +3. Otherwise, review all uncommitted changes + +## How the Loop Works + +``` +┌─────────────────────┐ +│ Run codex review │ +└──────────┬──────────┘ + │ + ┌─────▼─────┐ + │ Findings? │──── No ──→ Report clean ✓ + └─────┬──────┘ + │ Yes + ┌─────▼──────────┐ + │ Fix actionable │ + │ Skip false pos. │ + └─────┬──────────┘ + │ + ┌─────▼──────────┐ + │ Stop guards: │ + │ • cycle >= 3 │──── Any met ──→ Report & stop + │ • no progress │ + │ • no changes │ + └─────┬──────────┘ + │ None met + └──→ Re-run review ↑ +``` + +## Anti-Loop Safety + +| Guard | Condition | Rationale | +|-------|-----------|-----------| +| **Max cycles** | Cycle count reaches 3 | Hard cap prevents runaway loops | +| **No progress** | Findings >= previous cycle | Fixes aren't reducing issues | +| **No changes** | `git diff --stat` empty after fixes | All findings were false positives or unfixable | + +Any **one** of these triggers a stop. + +## Troubleshooting + +### Command not visible +Run `/help` and look for `codex-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 diff --git a/plugins/codex-review/commands/codex-review.md b/plugins/codex-review/commands/codex-review.md new file mode 100644 index 0000000..69b0c19 --- /dev/null +++ b/plugins/codex-review/commands/codex-review.md @@ -0,0 +1,60 @@ +--- +description: Run codex code review with auto-detection and iterative fix loop +argument-hint: [--commit ] +allowed-tools: Bash(codex:*, git:*, gh:*), Read, Edit, Write, Grep, Glob +--- + +Run an automated code review using the `codex` CLI. Follow each step in order. + +## Step 1: Check Availability + +Run `command -v codex` to verify codex is installed. If not found, stop silently — no error, no warning, no output. + +## Step 2: Detect Review Mode + +Determine which codex review mode to use: + +1. If `$1` is `--commit` and `$2` is provided, use: `codex review --commit $2` +2. Otherwise, check for an open PR on the current branch: + ``` + gh pr view --json baseRefName -q .baseRefName 2>/dev/null + ``` + - If a base branch is found, use: `codex review --base origin/` + - If no PR exists, use: `codex review --uncommitted` + +## Step 3: Execute Review + +Run the detected codex review command as a **background task** (`run_in_background: true`). Wait for it to complete. + +## Step 4: Parse Results + +Read the review output. If there are no findings, report that the review is clean and stop. + +## Step 5: Fix-and-Review Loop + +If findings exist, enter a fix-and-review loop: + +1. **Triage findings** by severity: + - **P1 (critical)** and **P2 (important)**: Fix directly — edit the code. + - **P3 (minor)** and **false positives**: Note them but do not fix. +2. **Check for changes** — run `git diff --stat` after fixing. + +### Anti-Loop Safety + +After each fix step, check these guards **before** re-running the review. **Stop immediately** if ANY is true: + +| Guard | Condition | +|-------|-----------| +| No changes | `git diff --stat` is empty after the fix step (all findings were false positives or unfixable) | +| Max cycles | Cycle count reaches **3** | +| No progress | Finding count is same or higher than previous cycle | + +If none of the stop conditions are met, go back to **Step 2** and re-run the review. + +## Step 6: Final Report + +Summarize the review outcome: + +- **Fixed**: List what was fixed and in which cycle +- **Skipped**: List false positives or unfixable findings with brief reasoning +- **Status**: Whether the review is now clean or findings remain diff --git a/plugins/codex-review/skills/review-workflow/SKILL.md b/plugins/codex-review/skills/review-workflow/SKILL.md new file mode 100644 index 0000000..06801a4 --- /dev/null +++ b/plugins/codex-review/skills/review-workflow/SKILL.md @@ -0,0 +1,46 @@ +--- +name: Code Review Workflow +description: This skill should be used when deciding whether to run a code review, interpreting codex review findings, understanding review severity levels, or determining the appropriate review strategy for code changes. Activates on "should I review this", "what does this codex finding mean", "review workflow", or after making code changes. +--- + +# Code Review Workflow + +Guidance for when, how, and why to run code reviews using the `/codex-review` command. + +## Review Mandate + +Code review is **mandatory** for all code changes. Run `/codex-review` proactively without waiting for the user to ask. Always run it as a background task. + +**Skip review** for trivial changes that don't touch code: docs-only edits, config-only changes, version bumps with no logic changes. + +## Only Review Your Own Code + +Only use `/codex-review` (codex CLI) for code you authored in the current session. When reviewing someone else's PR or code, review it directly — read the diff yourself and provide feedback without codex. + +## When to Review + +| Situation | Action | +|-----------|--------| +| Before first commit on a feature branch | Run `/codex-review` | +| After pushing commits to a PR | Run `/codex-review` | +| Reviewing a specific commit | Run `/codex-review --commit ` | +| Docs-only or config-only change | Skip review | + +The command auto-detects the correct mode (`--uncommitted`, `--base`, or `--commit`) — just run `/codex-review` without specifying a mode. + +## Interpreting Findings + +Codex findings fall into severity categories: + +| Severity | Action | Examples | +|----------|--------|----------| +| **P1 — Critical** | Must fix before commit/merge | Security vulnerabilities, data loss risks, broken logic | +| **P2 — Important** | Should fix, may proceed with justification | Error handling gaps, performance issues, missing validation | +| **P3 — Minor** | Nice to fix, safe to skip | Style inconsistencies, naming suggestions, minor simplifications | +| **False positive** | Note and skip | Findings that don't apply to the actual context | + +When the fix-and-review loop runs, fix P1 and P2 findings. Skip P3 findings and false positives — note them in the final report but do not attempt to fix. + +## When Codex Is Unavailable + +If the `codex` CLI is not installed, `/codex-review` silently does nothing — no error, no warning. This is intentional: the plugin should not block workflows in environments where codex is not available. From dbbcc8b1a0b0c58d8dec930c6834a221a15c6c51 Mon Sep 17 00:00:00 2001 From: vnz <1267662+vnz@users.noreply.github.com> Date: Fri, 20 Mar 2026 21:35:00 +0100 Subject: [PATCH 2/6] fix: use judgment-based triage instead of rigid severity rules, max 4 cycles - Severity informs priority but doesn't mechanically determine the action - Redefine "no progress" as all findings dismissed or already fixed - Increase max loop cycles from 3 to 4 Co-Authored-By: Claude Opus 4.6 (1M context) --- plugins/codex-review/README.md | 8 ++++---- plugins/codex-review/commands/codex-review.md | 13 +++++++------ .../codex-review/skills/review-workflow/SKILL.md | 2 +- 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/plugins/codex-review/README.md b/plugins/codex-review/README.md index 6f3d980..655bfc0 100644 --- a/plugins/codex-review/README.md +++ b/plugins/codex-review/README.md @@ -63,7 +63,7 @@ The command automatically determines the right review strategy: │ ┌─────▼──────────┐ │ Stop guards: │ - │ • cycle >= 3 │──── Any met ──→ Report & stop + │ • cycle >= 4 │──── Any met ──→ Report & stop │ • no progress │ │ • no changes │ └─────┬──────────┘ @@ -75,9 +75,9 @@ The command automatically determines the right review strategy: | Guard | Condition | Rationale | |-------|-----------|-----------| -| **Max cycles** | Cycle count reaches 3 | Hard cap prevents runaway loops | -| **No progress** | Findings >= previous cycle | Fixes aren't reducing issues | -| **No changes** | `git diff --stat` empty after fixes | All findings were false positives or unfixable | +| **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. diff --git a/plugins/codex-review/commands/codex-review.md b/plugins/codex-review/commands/codex-review.md index 69b0c19..6c33ca7 100644 --- a/plugins/codex-review/commands/codex-review.md +++ b/plugins/codex-review/commands/codex-review.md @@ -34,9 +34,10 @@ Read the review output. If there are no findings, report that the review is clea If findings exist, enter a fix-and-review loop: -1. **Triage findings** by severity: - - **P1 (critical)** and **P2 (important)**: Fix directly — edit the code. - - **P3 (minor)** and **false positives**: Note them but do not fix. +1. **Triage each finding** — use judgment, not rigid severity rules: + - Fix findings that are clearly correct and actionable. + - Dismiss false positives and findings that don't apply to the context. + - For borderline findings, fix if the improvement is clear; dismiss if debatable. 2. **Check for changes** — run `git diff --stat` after fixing. ### Anti-Loop Safety @@ -45,9 +46,9 @@ After each fix step, check these guards **before** re-running the review. **Stop | Guard | Condition | |-------|-----------| -| No changes | `git diff --stat` is empty after the fix step (all findings were false positives or unfixable) | -| Max cycles | Cycle count reaches **3** | -| No progress | Finding count is same or higher than previous cycle | +| No changes | `git diff --stat` is empty after the fix step (all findings were dismissed or already fixed) | +| Max cycles | Cycle count reaches **4** | +| No progress | All remaining findings from the current cycle were dismissed or already fixed in a previous cycle | If none of the stop conditions are met, go back to **Step 2** and re-run the review. diff --git a/plugins/codex-review/skills/review-workflow/SKILL.md b/plugins/codex-review/skills/review-workflow/SKILL.md index 06801a4..bb2856b 100644 --- a/plugins/codex-review/skills/review-workflow/SKILL.md +++ b/plugins/codex-review/skills/review-workflow/SKILL.md @@ -39,7 +39,7 @@ Codex findings fall into severity categories: | **P3 — Minor** | Nice to fix, safe to skip | Style inconsistencies, naming suggestions, minor simplifications | | **False positive** | Note and skip | Findings that don't apply to the actual context | -When the fix-and-review loop runs, fix P1 and P2 findings. Skip P3 findings and false positives — note them in the final report but do not attempt to fix. +When the fix-and-review loop runs, use judgment to triage each finding: fix what's clearly correct and actionable, dismiss false positives. Severity informs priority but doesn't mechanically determine the action — a P2 may be irrelevant in context, and a P3 may be worth fixing. ## When Codex Is Unavailable From ed7e15cac016e887bac69f7b1adafabb468875e9 Mon Sep 17 00:00:00 2001 From: vnz <1267662+vnz@users.noreply.github.com> Date: Fri, 20 Mar 2026 21:39:46 +0100 Subject: [PATCH 3/6] refactor: strip skill down to policy and interpretation only Remove content that overlaps with the command (background execution, silent fallback, mode detection, when-to-review table). Skill now only covers the review mandate, own-code rule, and severity guidance. Co-Authored-By: Claude Opus 4.6 (1M context) --- .../skills/review-workflow/SKILL.md | 21 ++----------------- 1 file changed, 2 insertions(+), 19 deletions(-) diff --git a/plugins/codex-review/skills/review-workflow/SKILL.md b/plugins/codex-review/skills/review-workflow/SKILL.md index bb2856b..cdd4e8d 100644 --- a/plugins/codex-review/skills/review-workflow/SKILL.md +++ b/plugins/codex-review/skills/review-workflow/SKILL.md @@ -5,11 +5,9 @@ description: This skill should be used when deciding whether to run a code revie # Code Review Workflow -Guidance for when, how, and why to run code reviews using the `/codex-review` command. - ## Review Mandate -Code review is **mandatory** for all code changes. Run `/codex-review` proactively without waiting for the user to ask. Always run it as a background task. +Code review is **mandatory** for all code changes. Run `/codex-review` proactively without waiting for the user to ask. **Skip review** for trivial changes that don't touch code: docs-only edits, config-only changes, version bumps with no logic changes. @@ -17,17 +15,6 @@ Code review is **mandatory** for all code changes. Run `/codex-review` proactive Only use `/codex-review` (codex CLI) for code you authored in the current session. When reviewing someone else's PR or code, review it directly — read the diff yourself and provide feedback without codex. -## When to Review - -| Situation | Action | -|-----------|--------| -| Before first commit on a feature branch | Run `/codex-review` | -| After pushing commits to a PR | Run `/codex-review` | -| Reviewing a specific commit | Run `/codex-review --commit ` | -| Docs-only or config-only change | Skip review | - -The command auto-detects the correct mode (`--uncommitted`, `--base`, or `--commit`) — just run `/codex-review` without specifying a mode. - ## Interpreting Findings Codex findings fall into severity categories: @@ -39,8 +26,4 @@ Codex findings fall into severity categories: | **P3 — Minor** | Nice to fix, safe to skip | Style inconsistencies, naming suggestions, minor simplifications | | **False positive** | Note and skip | Findings that don't apply to the actual context | -When the fix-and-review loop runs, use judgment to triage each finding: fix what's clearly correct and actionable, dismiss false positives. Severity informs priority but doesn't mechanically determine the action — a P2 may be irrelevant in context, and a P3 may be worth fixing. - -## When Codex Is Unavailable - -If the `codex` CLI is not installed, `/codex-review` silently does nothing — no error, no warning. This is intentional: the plugin should not block workflows in environments where codex is not available. +Severity informs priority but doesn't mechanically determine the action — a P2 may be irrelevant in context, and a P3 may be worth fixing. Use judgment. From 31ad4b3e9e978a664352b7af3f7888ec05549ff4 Mon Sep 17 00:00:00 2001 From: vnz <1267662+vnz@users.noreply.github.com> Date: Tue, 31 Mar 2026 10:29:11 +0200 Subject: [PATCH 4/6] refactor: rewrite codex-review plugin modeled on coderabbit architecture v2.0.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Separate concerns into command (execution), skill (autonomous behavior), and agent (subagent delegation) — matching the proven coderabbit plugin pattern. The v1 monolithic command was brittle and hard to trigger proactively. - commands/review.md: clean execution wrapper with context injection - skills/code-review/SKILL.md: when/how to review, autonomous fix loop - agents/code-reviewer.md: specialized subagent for thorough analysis - Removes old codex-review.md command and review-workflow skill Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 2 +- .../codex-review/.claude-plugin/plugin.json | 6 +- plugins/codex-review/README.md | 57 +++++++++-- plugins/codex-review/agents/code-reviewer.md | 94 +++++++++++++++++++ plugins/codex-review/commands/codex-review.md | 61 ------------ plugins/codex-review/commands/review.md | 70 ++++++++++++++ .../codex-review/skills/code-review/SKILL.md | 89 ++++++++++++++++++ .../skills/review-workflow/SKILL.md | 29 ------ 8 files changed, 306 insertions(+), 102 deletions(-) create mode 100644 plugins/codex-review/agents/code-reviewer.md delete mode 100644 plugins/codex-review/commands/codex-review.md create mode 100644 plugins/codex-review/commands/review.md create mode 100644 plugins/codex-review/skills/code-review/SKILL.md delete mode 100644 plugins/codex-review/skills/review-workflow/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 863ed22..150d094 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -68,7 +68,7 @@ }, { "name": "codex-review", - "description": "Automated code review using Codex CLI with autonomous fix-review cycles", + "description": "AI-powered code review in Claude Code using the Codex CLI", "version": "2.0.0", "source": "./plugins/codex-review", "category": "development", diff --git a/plugins/codex-review/.claude-plugin/plugin.json b/plugins/codex-review/.claude-plugin/plugin.json index 426bb69..2f0f5a7 100644 --- a/plugins/codex-review/.claude-plugin/plugin.json +++ b/plugins/codex-review/.claude-plugin/plugin.json @@ -1,11 +1,11 @@ { "name": "codex-review", - "version": "1.0.0", - "description": "Automated code review using OpenAI Codex CLI with auto-detection of review mode and iterative fix-and-review loop", + "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", "ci"] + "keywords": ["code-review", "codex", "review", "quality", "ai"] } diff --git a/plugins/codex-review/README.md b/plugins/codex-review/README.md index 655bfc0..ea22226 100644 --- a/plugins/codex-review/README.md +++ b/plugins/codex-review/README.md @@ -1,15 +1,16 @@ # codex-review -Automated code review plugin for Claude Code using the OpenAI Codex CLI. Provides a `/codex-review` slash command with automatic mode detection and an iterative fix-and-review loop. +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 | +| **Proactive review** | Skill triggers review after code changes without being asked | +| **Fix-and-review loop** | Fixes findings and re-reviews until clean (max 4 cycles) | | **Anti-loop safety** | Three independent guards prevent runaway loops | -| **Background execution** | Reviews run as background tasks | +| **Review agent** | Specialized subagent for thorough, autonomous code analysis | | **Silent fallback** | Does nothing if codex is not installed | ## Prerequisites @@ -29,23 +30,47 @@ Automated code review plugin for Claude Code using the OpenAI Codex CLI. Provide ## Usage +### Command + ```bash # Auto-detect mode (most common) -/codex-review +/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 --commit abc1234 +/codex-review:review --commit abc1234 ``` ### Mode Detection The command automatically determines the right review strategy: -1. If `--commit ` is passed, review that commit +1. If `--base ` 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 -## How the Loop Works +### Skill (Autonomous) + +The code-review skill triggers automatically when: + +- You ask Claude to review code +- Claude finishes implementing a feature (proactive review) +- You ask about code quality, bugs, or security + +### 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 ``` ┌─────────────────────┐ @@ -81,10 +106,26 @@ The command automatically determines the right review strategy: 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`. If missing, reinstall the plugin and restart Claude Code. +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: diff --git a/plugins/codex-review/agents/code-reviewer.md b/plugins/codex-review/agents/code-reviewer.md new file mode 100644 index 0000000..8f6003c --- /dev/null +++ b/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 diff --git a/plugins/codex-review/commands/codex-review.md b/plugins/codex-review/commands/codex-review.md deleted file mode 100644 index 6c33ca7..0000000 --- a/plugins/codex-review/commands/codex-review.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -description: Run codex code review with auto-detection and iterative fix loop -argument-hint: [--commit ] -allowed-tools: Bash(codex:*, git:*, gh:*), Read, Edit, Write, Grep, Glob ---- - -Run an automated code review using the `codex` CLI. Follow each step in order. - -## Step 1: Check Availability - -Run `command -v codex` to verify codex is installed. If not found, stop silently — no error, no warning, no output. - -## Step 2: Detect Review Mode - -Determine which codex review mode to use: - -1. If `$1` is `--commit` and `$2` is provided, use: `codex review --commit $2` -2. Otherwise, check for an open PR on the current branch: - ``` - gh pr view --json baseRefName -q .baseRefName 2>/dev/null - ``` - - If a base branch is found, use: `codex review --base origin/` - - If no PR exists, use: `codex review --uncommitted` - -## Step 3: Execute Review - -Run the detected codex review command as a **background task** (`run_in_background: true`). Wait for it to complete. - -## Step 4: Parse Results - -Read the review output. If there are no findings, report that the review is clean and stop. - -## Step 5: Fix-and-Review Loop - -If findings exist, enter a fix-and-review loop: - -1. **Triage each finding** — use judgment, not rigid severity rules: - - Fix findings that are clearly correct and actionable. - - Dismiss false positives and findings that don't apply to the context. - - For borderline findings, fix if the improvement is clear; dismiss if debatable. -2. **Check for changes** — run `git diff --stat` after fixing. - -### Anti-Loop Safety - -After each fix step, check these guards **before** re-running the review. **Stop immediately** if ANY is true: - -| Guard | Condition | -|-------|-----------| -| No changes | `git diff --stat` is empty after the fix step (all findings were dismissed or already fixed) | -| Max cycles | Cycle count reaches **4** | -| No progress | All remaining findings from the current cycle were dismissed or already fixed in a previous cycle | - -If none of the stop conditions are met, go back to **Step 2** and re-run the review. - -## Step 6: Final Report - -Summarize the review outcome: - -- **Fixed**: List what was fixed and in which cycle -- **Skipped**: List false positives or unfixable findings with brief reasoning -- **Status**: Whether the review is now clean or findings remain diff --git a/plugins/codex-review/commands/review.md b/plugins/codex-review/commands/review.md new file mode 100644 index 0000000..5d6152c --- /dev/null +++ b/plugins/codex-review/commands/review.md @@ -0,0 +1,70 @@ +--- +description: Run codex code review on your changes +argument-hint: [type] [--base ] +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 ` is specified, use: `codex review --base origin/` +2. If type is `committed`, check for an open PR: + ```bash + gh pr view --json baseRefName -q .baseRefName 2>/dev/null + ``` + - If a base branch is found, use: `codex review --base origin/` + - Otherwise, use: `codex review --uncommitted` +3. If type is `uncommitted`, use: `codex review --uncommitted` +4. If `--commit ` is specified, use: `codex review --commit ` +5. Default (no arguments): auto-detect: + - Check for open PR → `codex review --base origin/` + - 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. diff --git a/plugins/codex-review/skills/code-review/SKILL.md b/plugins/codex-review/skills/code-review/SKILL.md new file mode 100644 index 0000000..a9a13d2 --- /dev/null +++ b/plugins/codex-review/skills/code-review/SKILL.md @@ -0,0 +1,89 @@ +--- +name: code-review +description: Reviews code changes using Codex CLI. Use when user asks for code review, wants to check code quality, find bugs, or when you should proactively review code you just wrote. Activates on "review my code", "check for bugs", "code review", "run codex", or after implementing features. +--- + +# Codex Code Review + +AI-powered code review using the Codex CLI. Enables autonomous development workflows where you implement features, review code, and fix issues without manual intervention. + +## When to Use + +When user asks to: + +- Review code changes / Review my code / Review this +- Check code quality / Find bugs / Find issues +- Security review / Security check +- Get feedback on their code +- Run codex / Use codex review +- Implement a feature and review it +- Fix issues found in review + +**Proactive review**: After implementing code changes, run `/codex-review:review` without waiting for the user to ask. Skip review only for trivial changes that don't touch code (docs-only, config-only, version bumps). + +**Only review your own code**: Only use codex review for code you authored in the current session. When reviewing someone else's PR or code, review it directly — read the diff yourself and provide feedback without codex. + +## How to Review + +### 1. Check Prerequisites + +```bash +command -v codex >/dev/null 2>&1 && echo "codex found" || echo "codex not found" +``` + +**If not found**, tell user: + +``` +Please install Codex CLI first: +npm install -g @openai/codex +``` + +### 2. Run Review + +```bash +codex review +``` + +Mode options: + +- `--uncommitted` — Uncommitted changes only +- `--base origin/` — Compare against specific branch (use for PRs) +- `--commit ` — Review a specific commit +- Default (no flag) — auto-detects based on git state + +### 3. Present Results + +Group findings by severity and create a task list for issues found. + +| Severity | Action | Examples | +|----------|--------|----------| +| **P1 — Critical** | Must fix | Security vulnerabilities, data loss risks, broken logic | +| **P2 — Important** | Should fix | Error handling gaps, performance issues, missing validation | +| **P3 — Minor** | Nice to fix | Style inconsistencies, naming suggestions, minor simplifications | +| **False positive** | Skip | Findings that don't apply to the actual context | + +Severity informs priority but doesn't mechanically determine the action — a P2 may be irrelevant in context, and a P3 may be worth fixing. Use judgment. + +### 4. Fix Issues (Autonomous Workflow) + +When user requests implementation + review, or when proactively reviewing your own code: + +1. Implement the requested feature +2. Run `codex review` (auto-detect mode or `--uncommitted`) +3. Triage findings with judgment — fix actionable issues, dismiss false positives +4. Re-run review if fixes were applied +5. Repeat until clean or stop conditions are met + +### Anti-Loop Safety + +After each fix step, check these guards **before** re-running the review. **Stop immediately** if ANY is true: + +| Guard | Condition | +|-------|-----------| +| No changes | `git diff --stat` is empty after the fix step | +| Max cycles | Cycle count reaches **4** | +| No progress | All remaining findings were dismissed or already fixed in a previous cycle | + +## Documentation + +For more details on the Codex CLI: diff --git a/plugins/codex-review/skills/review-workflow/SKILL.md b/plugins/codex-review/skills/review-workflow/SKILL.md deleted file mode 100644 index cdd4e8d..0000000 --- a/plugins/codex-review/skills/review-workflow/SKILL.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -name: Code Review Workflow -description: This skill should be used when deciding whether to run a code review, interpreting codex review findings, understanding review severity levels, or determining the appropriate review strategy for code changes. Activates on "should I review this", "what does this codex finding mean", "review workflow", or after making code changes. ---- - -# Code Review Workflow - -## Review Mandate - -Code review is **mandatory** for all code changes. Run `/codex-review` proactively without waiting for the user to ask. - -**Skip review** for trivial changes that don't touch code: docs-only edits, config-only changes, version bumps with no logic changes. - -## Only Review Your Own Code - -Only use `/codex-review` (codex CLI) for code you authored in the current session. When reviewing someone else's PR or code, review it directly — read the diff yourself and provide feedback without codex. - -## Interpreting Findings - -Codex findings fall into severity categories: - -| Severity | Action | Examples | -|----------|--------|----------| -| **P1 — Critical** | Must fix before commit/merge | Security vulnerabilities, data loss risks, broken logic | -| **P2 — Important** | Should fix, may proceed with justification | Error handling gaps, performance issues, missing validation | -| **P3 — Minor** | Nice to fix, safe to skip | Style inconsistencies, naming suggestions, minor simplifications | -| **False positive** | Note and skip | Findings that don't apply to the actual context | - -Severity informs priority but doesn't mechanically determine the action — a P2 may be irrelevant in context, and a P3 may be worth fixing. Use judgment. From c93858878d33fadabd01856623c67e0953001fc6 Mon Sep 17 00:00:00 2001 From: vnz <1267662+vnz@users.noreply.github.com> Date: Tue, 31 Mar 2026 11:43:47 +0200 Subject: [PATCH 5/6] fix: correct committed mode fallback and hardcoded origin/ in review command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - `committed` mode now uses `codex review` (no flags) instead of falling back to --uncommitted when no PR exists — fixes wrong-diff bug - `--base` passes the ref as-is instead of prepending origin/, supporting multi-remote setups Found by codex review during plugin testing. Co-Authored-By: Claude Opus 4.6 (1M context) --- plugins/codex-review/commands/review.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/plugins/codex-review/commands/review.md b/plugins/codex-review/commands/review.md index 5d6152c..75430cb 100644 --- a/plugins/codex-review/commands/review.md +++ b/plugins/codex-review/commands/review.md @@ -40,13 +40,8 @@ command -v codex >/dev/null 2>&1 && echo "codex found" || echo "codex not found" Determine which mode to use from `$ARGUMENTS`: -1. If `--base ` is specified, use: `codex review --base origin/` -2. If type is `committed`, check for an open PR: - ```bash - gh pr view --json baseRefName -q .baseRefName 2>/dev/null - ``` - - If a base branch is found, use: `codex review --base origin/` - - Otherwise, use: `codex review --uncommitted` +1. If `--base ` is specified, use: `codex review --base ` (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 ` is specified, use: `codex review --commit ` 5. Default (no arguments): auto-detect: From 594e07f403c85f8edcdb779dd23d7e187854ade9 Mon Sep 17 00:00:00 2001 From: vnz <1267662+vnz@users.noreply.github.com> Date: Tue, 31 Mar 2026 11:49:36 +0200 Subject: [PATCH 6/6] fix: remove proactive review to avoid collision with coderabbit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both plugins installed = both would try to review autonomously after every code change. Match coderabbit's reactive pattern instead — only review when the user explicitly asks. Co-Authored-By: Claude Opus 4.6 (1M context) --- plugins/codex-review/README.md | 7 +++---- plugins/codex-review/skills/code-review/SKILL.md | 4 +--- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/plugins/codex-review/README.md b/plugins/codex-review/README.md index ea22226..a274133 100644 --- a/plugins/codex-review/README.md +++ b/plugins/codex-review/README.md @@ -7,7 +7,6 @@ AI-powered code review plugin for Claude Code using the [Codex CLI](https://gith | Feature | Description | |---------|-------------| | **Auto-detection** | Automatically selects `--uncommitted`, `--base`, or `--commit` mode | -| **Proactive review** | Skill triggers review after code changes without being asked | | **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 | @@ -54,13 +53,13 @@ The command automatically determines the right review strategy: 2. If the current branch has an open PR, review the full PR diff against its base 3. Otherwise, review all uncommitted changes -### Skill (Autonomous) +### Skill -The code-review skill triggers automatically when: +The code-review skill triggers when: - You ask Claude to review code -- Claude finishes implementing a feature (proactive review) - You ask about code quality, bugs, or security +- You request implementation + review in one go ### Agent diff --git a/plugins/codex-review/skills/code-review/SKILL.md b/plugins/codex-review/skills/code-review/SKILL.md index a9a13d2..49c0606 100644 --- a/plugins/codex-review/skills/code-review/SKILL.md +++ b/plugins/codex-review/skills/code-review/SKILL.md @@ -1,6 +1,6 @@ --- name: code-review -description: Reviews code changes using Codex CLI. Use when user asks for code review, wants to check code quality, find bugs, or when you should proactively review code you just wrote. Activates on "review my code", "check for bugs", "code review", "run codex", or after implementing features. +description: Reviews code changes using Codex CLI. Use when user asks for code review, wants to check code quality, find bugs, or wants autonomous fix-review cycles. Activates on "review my code", "check for bugs", "code review", "run codex", or "use codex review". --- # Codex Code Review @@ -19,8 +19,6 @@ When user asks to: - Implement a feature and review it - Fix issues found in review -**Proactive review**: After implementing code changes, run `/codex-review:review` without waiting for the user to ask. Skip review only for trivial changes that don't touch code (docs-only, config-only, version bumps). - **Only review your own code**: Only use codex review for code you authored in the current session. When reviewing someone else's PR or code, review it directly — read the diff yourself and provide feedback without codex. ## How to Review