claude-review

name

claude-review

description

Run read-only Claude Code reviews from Codex with explicit working-tree, branch, commit, range, or whole-repository scopes; arbitrary repository paths; custom focus or follow-up feedback; persistent review sessions; and background job controls. Use when a user asks Claude to review code, re-review changes without repeating rejected findings, compare a branch to a base, review a commit or repository, or manage a running Claude review.

Claude Review

Run the bundled runtime once and return its stdout faithfully. Do not reproduce its Git, session, or job logic with ad hoc shell commands.

Invoke the runtime

Resolve SKILL_DIR as the directory containing this SKILL.md, then run:

node "$SKILL_DIR/scripts/claude-review.mjs" <arguments>

Translate the user's natural request into the runtime interface. Preserve custom focus and follow-up feedback exactly. Read references/interface.md when scope or command mapping is unclear.

Examples:

node "$SKILL_DIR/scripts/claude-review.mjs"
node "$SKILL_DIR/scripts/claude-review.mjs" branch main -- "Focus on tenant isolation"
node "$SKILL_DIR/scripts/claude-review.mjs" again -- "I intentionally rejected the callback recommendation because it is public API"
node "$SKILL_DIR/scripts/claude-review.mjs" --resume-session SESSION_ID range PRIOR_HEAD..HEAD -- "Verify the bounded fixes"
node "$SKILL_DIR/scripts/claude-review.mjs" --dir /path/to/repo working --background
node "$SKILL_DIR/scripts/claude-review.mjs" status --dir /path/to/repo
node "$SKILL_DIR/scripts/claude-review.mjs" result --dir /path/to/repo

Behavioral contract

• Default to working scope and --effort max.
• Leave the Claude model unset unless the user requests one.
• Resume the active Claude review session for the repository and branch.
• Use --resume-session SESSION_ID with an exact new scope to resume a prior active session when branch identity changes, including an advancing detached review worktree. Use a committed scope from a clean checkout; working scope and --include-working are intentionally unavailable. The runtime requires the stored scope and HEAD to identify the same recorded commit tip, requires that tip to remain an ancestor of the current HEAD, and requires the requested scope tip to equal that HEAD. No other active session may already own the destination checkout identity. A successful resume follows the current checkout identity. Session artifacts are scoped to the same working-tree root, so a sibling linked worktree cannot select the ID.
• Use new for a fresh session, again for the previous scope, and reset to forget the active session without deleting artifacts.
• For a focused fix after a detached review, pass --resume-session again with the exact prior-to-current range; again repeats the previous scope definition instead of deriving that delta.
• Treat continuity as optional. Once a Claude process starts, any error, timeout, cancellation, worker death, checkout mismatch, malformed result, or persistence failure that prevents its result from being applied retires the plugin session at its last accepted scope and HEAD. Cancellation ends continuity. Start a new isolated session over the unapplied delta; do not broaden the scope merely to recreate reviewer context.
• Keep the selected working-tree root untouched while an explicit --resume-session review runs. Only that path samples its named-or-detached identity, HEAD, and cleanliness before invoking Claude and before applying the result; a transient change restored between samples cannot be detected. A background review may overlap work in another checkout.
• Forward later user decisions as focus text so Claude receives them in its transcript.
• Choose foreground or background execution from the workflow. Prefer foreground when the result gates the current action; prefer background when useful independent work can continue or the review is likely to take a long time; ask the user when neither choice is clearly better. Honor an explicit user preference.
• Do not impose an agent-side timeout or treat quiet elapsed time alone as a stalled review. Let a healthy review run until it completes, the user cancels it, or the runtime reports a failure. Poll in bounded increments and keep the user updated while waiting.