git-review

# Git Review Interactive annotation-based code review using editor overlays. ## Activation Triggers - "git review", "review changes", "review my changes" - "annotate changes", "interactive review" - "review diff", "annotate diff" ## How It Works 1. Script generates a cleaned-up diff file (friendly headers, no technical noise) 2. Opens in `$EDITOR` via agterm overlay, tmux popup, kitty overlay, or wezterm split-pane 3. User adds annotations (comments, change requests) directly in the file 4. Script returns user's annotations as a git diff 5. Claude reads annotations, fixes code in the real repo 6. Script regenerates fresh diff (reflecting fixes), opens again 7. Loop until user closes editor without changes ## Workflow ### Step 1: Run the script ```bash ${CLAUDE_PLUGIN_ROOT}/skills/git-review/scripts/git-review.py [base_ref] ``` - No arguments: auto-detects uncommitted changes or branch vs default branch - With argument: diffs against the specified ref (branch, tag, commit, `HEAD~3`) ### Step 2: Process annotations If the script produces output (stdout), the user made annotations. The output is a git diff showing what the user added/changed in the review file. Read the diff carefully: - **Added lines (+)**: user's annotations, comments, or change requests - **Removed lines (-)**: user wants something removed or changed - **Modified lines (- then +)**: user replaced text to show desired change Each annotation is in context — the surrounding `===` file headers and diff content show which file and code area the annotation refers to. ### Step 3: Plan changes Enter plan mode (EnterPlanMode) to analyze annotations and design the fix approach: - list each annotation and which file/code area it refers to - describe the planned changes for each annotation - get user approval before modifying any code ### Step 4: Address annotations After plan approval, fix the actual source code in the real repository. Each annotation is a directive — treat it as a code review comment that must be addressed. ### Step 5: Loop After fixing code, run the script again. It regenerates a fresh diff reflecting the fixes and opens the editor. The user can: - Add more annotations → go back to step 2 (plan + fix again) - Close without changes → review complete (no stdout output) ### Step 6: Done When the script produces no output, the review is complete. Inform the user. ## Script Arguments | Argument | Description | |----------|-------------| | (none) | auto-detect: uncommitted changes if present, otherwise branch vs default branch | | `<ref>` | diff against specific ref: `master`, `main`, `HEAD~5`, `v1.2.0`, etc. | | `--clean` | remove the review tracking repo from /tmp | | `--test` | run embedded unit tests | ## Example Session ``` User: "review my changes" → run: git-review.py → editor opens with cleaned diff → user adds "this should validate input" next to a handler → user closes editor → stdout shows the annotation → enter plan mode: "annotation requests input validation in handler.go, plan: add validate() call" → user approves plan → Claude adds input validation to the handler → run: git-review.py (again) → editor opens with updated diff (validation now visible) → user closes without changes → no stdout → review complete → "review complete, all annotations addressed" ``` ## Requirements - agterm, tmux, kitty, or wezterm terminal (for editor overlay) - `$EDITOR` set (defaults to vi) - git - agterm users: needs `agtermctl` on PATH (bundled with agterm); no extra config; pane-scoped overlays need agterm 0.20.0+ - kitty users: kitty.conf must have `allow_remote_control yes` and `listen_on unix:/tmp/kitty-$KITTY_PID`