code-review plugin

The code-review plugin runs automated code review on a branch, a staged change, specific files, or a GitHub PR.

Command

claude /code-review:start [scope] [--github] [--hygiene-only] [--base <ref>] [--since-last-review] [--full-review]

Scopes:

• no argument — review the current branch vs main
• staged — review staged changes
• file1 file2 ... — review specific files
• 123 — review PR #123

Flags:

• --github — CI handoff mode, posts inline comments via gh
• --hygiene-only — run only the deterministic hygiene pass
• --base <ref> — override the base ref
• --since-last-review — incremental review since the last stored review hash
• --full-review — ignore the incremental cache

How it works

1. Hygiene pass — deterministic checks (file size, trailing whitespace, TODO density, and so on).
2. Partitioning — splits the diff into partitions for parallel review.
3. Risk-based routing — picks models for each partition based on risk signals.
4. Parallel review — launches code:code-review-worker subagents concurrently with run_in_background: true.
5. Finding collection — aggregates findings into code-review-findings.json.
6. Validation — runs Pydantic validation (reusing validate_judge_report.py from judges).
7. Summary and verdict — writes code-review-summary.md and verdict.json (approve | needs_attention | changes_requested).
8. GitHub posting (--github) — posts inline comments and a summary comment to the PR via gh, resolves outdated threads.

Caching

• Hash-based cache — findings are keyed by a hash of the diff, so re-running on the same diff is instant.
• Incremental — --since-last-review only reviews new changes since the last cached review.
• Session work directory — .closedloop-ai/code-review/cr-<random>/.

Outputs

Dependencies on other plugins

• code:code-review-worker and code:code-review-guidelines — subagent and guidelines bundle.
• judges — reuses validate_judge_report and JUDGE_REGISTRY by sys.path import.

Python tooling

plugins/code-review/tools/python/code_review_helpers.py exposes a 20-plus subcommand CLI:

setup parse-diff hygiene partition route validate compute-hashes
cache-check cache-update auto-incremental finalize-cache
review-state-read review-state-write post-comments resolve-threads
session-tokens footer resolve-scope fetch-intent classify-intent
collect-findings verdict prep-assets extract-patches

Fix skill

The code-review:fix skill (under skills/fix/) provides a remediation playbook when you want an agent to address the findings.

When to run

• On every PR via CI (the --github flag is designed for this).
• Locally before pushing, to catch issues before they hit the PR.
• Incrementally during development to review the current branch.

Use --since-last-review in long-lived branches to avoid re-reviewing unchanged code.