| name | git-review |
| description | Interactive git diff annotation review. Generates a cleaned-up diff, opens in editor for user annotations, and addresses feedback in a loop. Activates on "git review", "review changes", "review my changes", "annotate changes", "interactive review". |
| allowed-tools | Bash, Read, Edit, Write, Grep, Glob |
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
- Script generates a cleaned-up diff file (friendly headers, no technical noise)
- Opens in
$EDITOR via agterm overlay, tmux popup, kitty overlay, or wezterm split-pane
- User adds annotations (comments, change requests) directly in the file
- Script returns user's annotations as a git diff
- Claude reads annotations, fixes code in the real repo
- Script regenerates fresh diff (reflecting fixes), opens again
- Loop until user closes editor without changes
Workflow
Step 1: Run the script
${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
