feat(review): add /cursor:review — read-only diff review by a Cursor model

Adds a code-review command modelled on openai/codex-plugin-cc's
/codex:review, adapted to the Cursor CLI. The plugin collects the git
diff itself (working tree, or a branch vs --base <ref>), embeds it in a
strict review-only prompt, runs cursor-agent over it, and returns the
findings (Blocking / Should-fix / Nits + verdict) verbatim.

- Targets: auto (dirty tree → working-tree, clean → branch vs default),
  plus --scope auto|working-tree|branch and --base <ref>.
- --adversarial challenges the design, not only implementation defects.
- Tracked as a normal job: /cursor:status, /cursor:result, /cursor:cancel
  all apply; supports --background/--wait, --model, --timeout, focus text.
- Read-only guarantee: a post-flight check marks the job failed if the run
  touches the working tree, so a review can never silently become an edit.
- New collectReviewContext helpers in scripts/lib/git.mjs; tests + fixtures.

Docs: README "What you get" + Usage subsection, reworked the old
"no review command" section into "A second opinion", CHANGELOG entry.

Author: freema

CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## Unreleased
+
+### Added
+
+- **`/cursor:review`** — read-only code review of your git diff by a Cursor model, modelled on `openai/codex-plugin-cc`'s `/codex:review`. The plugin collects the diff itself (working tree, or branch vs a `--base <ref>`), embeds it in a strict review-only prompt, runs `cursor-agent` over it, and returns the findings (Blocking / Should-fix / Nits + verdict) verbatim. Supports `--scope auto|working-tree|branch`, `--adversarial` (challenge the design), `--model`, `--background`/`--wait`, `--timeout`, and free-form focus text. Tracked as a normal job, so `/cursor:status`, `/cursor:result`, and `/cursor:cancel` apply. A post-flight check marks the job `failed` if the run touches the working tree, so a review can never silently become an edit. New `collectReviewContext` helpers in `scripts/lib/git.mjs`.
+
 ## 0.2.2 — resume bug fix + safer default model
 
 ### Fixed

README.md

@@ -117,10 +117,11 @@ What lives where after a run:
 
 ## What you get
 
-Nine slash commands under the `cursor:` namespace:
+Ten slash commands under the `cursor:` namespace:
 
 - **`/cursor:delegate`** — hand a coding task to Cursor, foreground or background.
 - **`/cursor:from-plan`** — turn a Claude Code plan (from plan mode) into a `tasks/<file>.md` and hand it off to Cursor.
+- **`/cursor:review`** — read-only code review of your git diff by a Cursor model. Reports findings; never edits files.
 - **`/cursor:browser`** — verify a URL / flow in a real browser via Cursor's `chrome-devtools` MCP.
 - **`/cursor:status`** — list recent jobs or inspect a specific one.
 - **`/cursor:result`** — print the final output of a finished job.
@@ -141,9 +142,11 @@ Cursor CLI has its own plan mode and it is fine, but execution is where Cursor r
 
 So: Claude plans, Cursor writes, Claude reviews, repeat. Glued together by seven slash commands and one subagent.
 
-## Why not just `/codex:review`-style?
+## A second opinion: `/cursor:review`
 
-This plugin is built around delegating _execution_ — writing code — to Cursor's Composer 2 for speed. Claude Code stays the orchestrator, planner, and reviewer. There is intentionally **no** `/cursor:review` or `/cursor:adversarial-review` command: Cursor is the "doer" here, not the critic. If you want review, ask Claude to review Cursor's diff in the usual way.
+The core loop stays **Claude plans, Cursor writes, Claude reviews** — that is where Claude Code earns its keep. But sometimes you want a _second_ reviewer on the same diff: a different model with a fresh perspective, or a deeper pass from `gpt`/`opus`/`gemini` while Claude keeps its context for orchestration. That is what `/cursor:review` is for.
+
+It is modelled on [`openai/codex-plugin-cc`](https://github.com/openai/codex-plugin-cc)'s `/codex:review`, adapted to the Cursor CLI: the plugin collects the git diff itself (working tree or branch vs a base), hands it to a Cursor model with a strict **review-only** prompt, and returns the findings verbatim. It never edits your files — a post-flight check fails the job if the run touches the working tree, so a review can't quietly turn into an edit. See [`/cursor:review`](#cursorreview-flags-focus) under Usage for flags and examples.
 
 ## Usage
 
@@ -196,6 +199,35 @@ Examples:
 
 This is the closest thing to "plan in Claude, execute in Cursor" in one session: Claude does the thinking, Cursor does the typing, and the task file is a durable contract between the two.
 
+### `/cursor:review [flags] [focus...]`
+
+Read-only code review of your git diff by a Cursor model. The plugin collects the diff itself, embeds it in a strict review-only prompt, runs `cursor-agent` over it, and prints the findings verbatim — grouped Blocking / Should-fix / Nits with a one-line verdict. It does **not** edit files; if the run touches the working tree anyway, a post-flight check marks the job `failed` and flags it. Tracked as a normal job, so `/cursor:status`, `/cursor:result` and `/cursor:cancel` all work on it.
+
+By default it picks the target automatically: a dirty working tree is reviewed as-is; a clean tree falls back to a branch diff against the detected default branch. Any trailing text is passed as a reviewer **focus**.
+
+| Flag                                 | Default           | Effect                                                                                             |
+| ------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------- |
+| `--base <ref>`                       | auto              | Review the branch diff `<ref>...HEAD` (merge-base) instead of the working tree.                    |
+| `--scope auto\|working-tree\|branch` | `auto`            | Force the target. `working-tree` = uncommitted changes; `branch` = vs the detected default branch. |
+| `--adversarial`                      | off               | Challenge the design and assumptions, not just implementation defects.                             |
+| `--model <id>`                       | `auto`            | Same aliases as `/cursor:delegate`. Use `gpt`/`opus`/`gemini` for a deeper review.                 |
+| `--background`                       | off               | Detach; returns a job id immediately. Read it later with `/cursor:result`.                         |
+| `--wait`                             | on                | Block until the review finishes (default unless `--background`).                                   |
+| `--timeout <sec>`                    | `1800`            | Kill the review if it exceeds this.                                                                |
+| `--no-git-check`                     | off               | Allow running outside a git repo (rarely useful — there is no diff to review).                     |
+
+Examples:
+
+```
+/cursor:review                                  # review the current working-tree diff
+/cursor:review --base main                      # review this branch vs main
+/cursor:review --scope branch --model gpt       # branch diff, deeper model
+/cursor:review --adversarial "is the retry/backoff design sound under load?"
+/cursor:review --background --model opus         # detach; /cursor:result when ready
+```
+
+This is a **second opinion**, not a replacement for Claude reviewing the diff in-session. Reach for it when you want a different model's eyes on the change, or to offload a large review while Claude keeps orchestrating.
+
 ### `/cursor:browser <url> <what to verify...>`
 
 Verify a page or a flow in a **real browser** via Cursor's `chrome-devtools` MCP. This is read-only by design — Cursor navigates, interacts, checks console/network and reports back; it will not modify your source files.

plugins/cursor/commands/review.md

@@ -0,0 +1,9 @@
+---
+description: Read-only code review of your git diff by a Cursor model. Reports findings; never edits files.
+argument-hint: '[--background] [--wait] [--adversarial] [--base <ref>] [--scope auto|working-tree|branch] [--model <id>] [--timeout <sec>] [focus...]'
+allowed-tools: Bash(node:*)
+---
+
+!`node "${CLAUDE_PLUGIN_ROOT}/scripts/review.mjs" -- "$ARGUMENTS"`
+
+Render the tool output to the user verbatim — it is a code review, do not paraphrase or summarise it, and do not act on the findings yourself. If the job ran in the foreground, present the **Review** section as-is. If it was started in the background, show the returned job id and the `/cursor:status` / `/cursor:result` hints. This command is review-only: never apply the fixes it suggests unless the user explicitly asks in a follow-up.

plugins/cursor/package.json

@@ -46,7 +46,8 @@
     "resume": "node scripts/resume.mjs",
     "sessions": "node scripts/sessions.mjs",
     "setup": "node scripts/setup.mjs",
-    "browser": "node scripts/browser.mjs"
+    "browser": "node scripts/browser.mjs",
+    "review": "node scripts/review.mjs"
   },
   "devDependencies": {
     "@eslint/js": "^9.16.0",

plugins/cursor/scripts/lib/git.mjs

@@ -1,3 +1,5 @@
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
 import { run } from './run.mjs';
 
 /**
@@ -24,3 +26,246 @@ export async function repoRoot(cwd = process.cwd()) {
   if (res.exitCode === 0) return res.stdout.trim() || cwd;
   return cwd;
 }
+
+// --- review-context collection ---------------------------------------------
+// Helpers below gather the git state a code review needs (status, diff stat,
+// diff body, untracked file contents) so the review prompt is self-contained
+// and the reviewer never has to mutate the tree to see what changed.
+
+const MAX_DIFF_BYTES = 256 * 1024;
+const MAX_UNTRACKED_BYTES = 32 * 1024;
+
+function git(cwd, args) {
+  return run('git', args, { cwd, timeoutMs: 15_000 });
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {Promise<string>}
+ */
+export async function currentBranch(cwd = process.cwd()) {
+  const res = await git(cwd, ['branch', '--show-current']);
+  return res.stdout.trim() || 'HEAD';
+}
+
+/**
+ * Best-effort detection of the repo's default branch. Returns null when none
+ * of the usual suspects exist, so callers can ask the user for `--base`.
+ *
+ * @param {string} [cwd]
+ * @returns {Promise<string|null>}
+ */
+export async function detectDefaultBranch(cwd = process.cwd()) {
+  const sym = await git(cwd, ['symbolic-ref', '--quiet', 'refs/remotes/origin/HEAD']);
+  if (sym.exitCode === 0) {
+    const head = sym.stdout.trim();
+    if (head.startsWith('refs/remotes/origin/')) {
+      return head.replace('refs/remotes/origin/', 'origin/');
+    }
+  }
+  for (const cand of ['main', 'master', 'trunk']) {
+    const local = await git(cwd, ['show-ref', '--verify', '--quiet', `refs/heads/${cand}`]);
+    if (local.exitCode === 0) return cand;
+    const remote = await git(cwd, [
+      'show-ref',
+      '--verify',
+      '--quiet',
+      `refs/remotes/origin/${cand}`,
+    ]);
+    if (remote.exitCode === 0) return `origin/${cand}`;
+  }
+  return null;
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {Promise<{staged: string[], unstaged: string[], untracked: string[], isDirty: boolean}>}
+ */
+export async function workingTreeStatus(cwd = process.cwd()) {
+  const split = (s) => s.trim().split('\n').filter(Boolean);
+  const staged = split((await git(cwd, ['diff', '--cached', '--name-only'])).stdout);
+  const unstaged = split((await git(cwd, ['diff', '--name-only'])).stdout);
+  const untracked = split((await git(cwd, ['ls-files', '--others', '--exclude-standard'])).stdout);
+  return {
+    staged,
+    unstaged,
+    untracked,
+    isDirty: staged.length + unstaged.length + untracked.length > 0,
+  };
+}
+
+function looksBinary(buf) {
+  const len = Math.min(buf.length, 8_000);
+  for (let i = 0; i < len; i += 1) if (buf[i] === 0) return true;
+  return false;
+}
+
+function section(title, body) {
+  const trimmed = (body ?? '').trim();
+  return `## ${title}\n\n${trimmed ? trimmed : '(none)'}\n`;
+}
+
+function capDiff(diff, maxBytes) {
+  if (Buffer.byteLength(diff, 'utf8') <= maxBytes) return { text: diff, truncated: false };
+  const slice = Buffer.from(diff, 'utf8').subarray(0, maxBytes).toString('utf8');
+  const lastNl = slice.lastIndexOf('\n');
+  return { text: slice.slice(0, lastNl > 0 ? lastNl : slice.length), truncated: true };
+}
+
+function untrackedSection(cwd, files) {
+  if (files.length === 0) return '(none)';
+  const parts = [];
+  for (const rel of files) {
+    const abs = join(cwd, rel);
+    let st;
+    try {
+      st = statSync(abs);
+    } catch {
+      parts.push(`### ${rel}\n(unreadable)`);
+      continue;
+    }
+    if (st.isDirectory()) {
+      parts.push(`### ${rel}/\n(directory — contents omitted)`);
+      continue;
+    }
+    if (st.size > MAX_UNTRACKED_BYTES) {
+      parts.push(
+        `### ${rel}\n(skipped: ${st.size} bytes exceeds ${MAX_UNTRACKED_BYTES} byte limit)`,
+      );
+      continue;
+    }
+    let buf;
+    try {
+      buf = readFileSync(abs);
+    } catch {
+      parts.push(`### ${rel}\n(unreadable)`);
+      continue;
+    }
+    if (looksBinary(buf)) {
+      parts.push(`### ${rel}\n(binary file)`);
+      continue;
+    }
+    parts.push([`### ${rel}`, '```', buf.toString('utf8').trimEnd(), '```'].join('\n'));
+  }
+  return parts.join('\n\n');
+}
+
+/**
+ * @typedef {Object} ReviewContext
+ * @property {'working-tree'|'branch'} [mode]
+ * @property {string} [label]      Human-readable target description.
+ * @property {string} [baseRef]
+ * @property {string} [body]       Markdown diff context for the prompt.
+ * @property {string[]} [changedFiles]
+ * @property {boolean} [truncated]
+ * @property {boolean} [isEmpty]   True when there is nothing to review.
+ * @property {string} [error]      Set when the target could not be resolved.
+ */
+
+/**
+ * Resolve and collect the git context for a review.
+ *
+ * @param {string} cwd
+ * @param {{scope?: 'auto'|'working-tree'|'branch', base?: string|null, maxDiffBytes?: number}} [opts]
+ * @returns {Promise<ReviewContext>}
+ */
+export async function collectReviewContext(cwd, opts = {}) {
+  const scope = opts.scope ?? 'auto';
+  const base = opts.base ?? null;
+  const maxDiffBytes = opts.maxDiffBytes ?? MAX_DIFF_BYTES;
+  const branch = await currentBranch(cwd);
+
+  let mode;
+  let baseRef = base;
+  if (base) {
+    mode = 'branch';
+  } else if (scope === 'working-tree') {
+    mode = 'working-tree';
+  } else if (scope === 'branch') {
+    mode = 'branch';
+    baseRef = await detectDefaultBranch(cwd);
+  } else {
+    const st = await workingTreeStatus(cwd);
+    if (st.isDirty) {
+      mode = 'working-tree';
+    } else {
+      mode = 'branch';
+      baseRef = await detectDefaultBranch(cwd);
+    }
+  }
+
+  if (mode === 'branch' && !baseRef) {
+    return {
+      error: 'Could not detect a default branch. Pass --base <ref> or use --scope working-tree.',
+    };
+  }
+
+  if (mode === 'working-tree') {
+    const st = await workingTreeStatus(cwd);
+    const changedFiles = [...new Set([...st.staged, ...st.unstaged, ...st.untracked])].sort();
+    if (!st.isDirty) {
+      return { mode, label: `working tree on ${branch}`, changedFiles: [], isEmpty: true };
+    }
+    const status = (await git(cwd, ['status', '--short', '--untracked-files=all'])).stdout.trim();
+    const stat = (await git(cwd, ['diff', '--stat', 'HEAD'])).stdout.trim();
+    const { text: diff, truncated } = capDiff(
+      (await git(cwd, ['diff', '--no-ext-diff', 'HEAD'])).stdout,
+      maxDiffBytes,
+    );
+    const body = [
+      section('Status', status),
+      section('Diff stat', stat),
+      section(
+        'Diff (tracked files vs HEAD)',
+        diff + (truncated ? '\n\n…[diff truncated — inspect the remaining files read-only]…' : ''),
+      ),
+      section('Untracked files', untrackedSection(cwd, st.untracked)),
+    ].join('\n');
+    return {
+      mode,
+      label: `working tree on ${branch} (${changedFiles.length} file(s))`,
+      body,
+      changedFiles,
+      truncated,
+      isEmpty: false,
+    };
+  }
+
+  const mb = await git(cwd, ['merge-base', 'HEAD', baseRef]);
+  if (mb.exitCode !== 0) {
+    return { error: `Could not compute a merge-base with "${baseRef}". Is it a valid ref?` };
+  }
+  const range = `${baseRef}...HEAD`;
+  const changedFiles = (await git(cwd, ['diff', '--name-only', range])).stdout
+    .trim()
+    .split('\n')
+    .filter(Boolean);
+  if (changedFiles.length === 0) {
+    return { mode, label: `${branch} vs ${baseRef}`, baseRef, changedFiles: [], isEmpty: true };
+  }
+  const log = (
+    await git(cwd, ['log', '--oneline', '--no-decorate', `${baseRef}..HEAD`])
+  ).stdout.trim();
+  const stat = (await git(cwd, ['diff', '--stat', range])).stdout.trim();
+  const { text: diff, truncated } = capDiff(
+    (await git(cwd, ['diff', '--no-ext-diff', range])).stdout,
+    maxDiffBytes,
+  );
+  const body = [
+    section('Commits', log),
+    section('Diff stat', stat),
+    section(
+      `Diff (${range})`,
+      diff + (truncated ? '\n\n…[diff truncated — inspect the remaining files read-only]…' : ''),
+    ),
+  ].join('\n');
+  return {
+    mode,
+    label: `${branch} vs ${baseRef} (${changedFiles.length} file(s))`,
+    baseRef,
+    body,
+    changedFiles,
+    truncated,
+    isEmpty: false,
+  };
+}