diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 890c4ab..150d094 100644 --- a/.claude-plugin/marketplace.json +++ b/.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" + } } ] } 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..2f0f5a7 --- /dev/null +++ b/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"] +} diff --git a/plugins/codex-review/README.md b/plugins/codex-review/README.md new file mode 100644 index 0000000..a274133 --- /dev/null +++ b/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 ` 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 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/review.md b/plugins/codex-review/commands/review.md new file mode 100644 index 0000000..75430cb --- /dev/null +++ b/plugins/codex-review/commands/review.md @@ -0,0 +1,65 @@ +--- +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 ` (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: + - 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..49c0606 --- /dev/null +++ b/plugins/codex-review/skills/code-review/SKILL.md @@ -0,0 +1,87 @@ +--- +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 wants autonomous fix-review cycles. Activates on "review my code", "check for bugs", "code review", "run codex", or "use codex review". +--- + +# 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 + +**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: