git-review
npx machina-cli add skill umputun/cc-thingz/git-review --openclawGit 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
$EDITORvia 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
- tmux, kitty, or wezterm terminal (for editor overlay)
$EDITORset (defaults to micro)- git
- kitty users: kitty.conf must have
allow_remote_control yesandlisten_on unix:/tmp/kitty-$KITTY_PID
Source
git clone https://github.com/umputun/cc-thingz/blob/master/plugins/review/skills/git-review/SKILL.mdView on GitHub Overview
Git-review provides an interactive, editor-based workflow to annotate and refine code changes. It generates a cleaned diff, opens it in your editor for comments, and loops through planning and fixes until no changes remain. It activates on triggers like git review, review changes, annotate changes, and interactive review.
How This Skill Works
The tool creates a readable, cleaned diff and opens it in your editor via tmux popup, kitty overlay, or wezterm split-pane. You add annotations directly in the diff; the tool returns your annotations as a git diff. A subsequent pass applies fixes in the real repo, regenerates a fresh diff, and reopens the editor to repeat the cycle until you close without changes.
When to Use It
- Before committing: annotate and discuss a cleaned diff of your uncommitted changes.
- Review changes against a base ref (branch, tag, or HEAD~N) before merging.
- Annotate complex diffs with comments in the overlay to guide targeted fixes.
- Plan changes in Plan Mode and obtain approval before applying changes.
- Iterate through fixes and re-run the diff until no further changes are needed.
Quick Start
- Step 1: Run the script: ${CLAUDE_PLUGIN_ROOT}/skills/git-review/scripts/git-review.py [base_ref] (no args auto-detects changes).
- Step 2: Edit the opened cleaned diff in your editor to add annotations and comments.
- Step 3: Save/close the editor to see the annotations as a diff; proceed to plan mode and approve changes before applying.
Best Practices
- Keep annotations concise and context-rich, including the surrounding header and diff context.
- Use the file headers and diff blocks to map each annotation to the exact file and location.
- Run in a supported terminal with $EDITOR set and use the editor overlay workflow (tmux kitty wezterm).
- Review the generated diff carefully before moving to the planning phase.
- If you need to reset, use --clean to remove the review tracking workspace and start fresh.
Example Use Cases
- Annotate a Go handler: add a validation comment next to a function, then re-run to see the updated diff.
- Review a JS feature: annotate a race condition and plan a fix, then apply changes and re-check.
- Prepare a PR by cleaning up a messy local diff with targeted comments on each file.
- Plan-mode for adding error handling in a Python module and verify the plan before implementation.
- Iterative refactor review on a feature branch to ensure all annotations are addressed before merge.
