code-review-loop

Code Review Loop (up to 3 iterations)

Input: a git base SHA (or other explicit range) to review against (for example: <sha> or HEAD~1).

Preconditions

• Confirm you are in the intended repo: git rev-parse --show-toplevel
• Ensure you have a base commit SHA (prefer the commit from before the change set).
  • If none was provided and you cannot choose confidently, ask the user for the correct base SHA.
• Start from a clean working tree (recommended):
  • git status --porcelain should be empty.
  • If it’s not empty, either commit/stash first or ask the user what to do (don’t mix unrelated changes into review fixes).
• Ensure both CLIs are available (codex and claude) because reviewer/responder must be different vendors.

Expected runtime

Typically runs 15–45 minutes, but allow at least 120 minutes.

Do not interrupt/restart the subagent if it looks stuck. The loop script owns stuck/timeout handling and will exit on its own when it completes or when --timeout is reached. Prefer watching the periodic heartbeat output (--heartbeat-seconds) instead of tailing logs.

Why Claude sometimes looked “stuck”

Claude Code print mode can be silent in --output-format text until it finishes (including during tool work). This repo defaults Claude subprocesses to --output-format stream-json --include-partial-messages so the wrapper sees measurable progress and inactivity timeouts mainly trigger on true hangs.

Loop

Run the review loop script:

resolve_skill_dir() {
  local name="$1"
  local repo_root=""
  repo_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

  local candidates=(
    "$repo_root/.agents/skills/$name"
    "$repo_root/.claude/skills/$name"
    "$HOME/.agents/skills/$name"
    "$HOME/.codex/skills/$name"
    "$HOME/.claude/skills/$name"
  )

  for d in "${candidates[@]}"; do
    if [[ -d "$d" ]]; then
      echo "$d"
      return 0
    fi
  done

  echo "Error: skill '$name' not found in repo-scoped or user-scoped skill dirs." >&2
  return 1
}

CODE_REVIEW_LOOP_SKILL_DIR="$(resolve_skill_dir code-review-loop)"
python3 "$CODE_REVIEW_LOOP_SKILL_DIR/scripts/run_review_loop.py" <base-sha>