Annotate AI Code Changes in Terminal with Revdiff and Claude Code
Job to be done: Review and annotate AI-generated code changes and plans within a terminal session
🇳🇬 Ways to use this in Nigeria
Ideas to get you started, adapt to your situation.
- Student
Review AI-generated Python code for your CSC401 e-commerce project, using Revdiff in the terminal to correct logic errors or add specific features before submitting your assignment.
- 9-5 employee
As a software engineer, use Revdiff to review AI-generated code for a new feature in your company's customer relationship management (CRM) system, ensuring it integrates correctly with existing modules before code review.
- Entrepreneur
As a technical founder, use Revdiff to review AI-generated code for new features in your startup's mobile app backend, ensuring it meets your product's security standards before pushing to production.
What you’ll get
A fast way to review the code an AI wrote for you without leaving your terminal. Revdiff shows you the AI’s changes as a “diff” (a side-by-side view of what was added and removed), you scribble notes on the lines you want changed, and those notes go straight back to the AI so it can revise. It tightens the back-and-forth of AI-assisted coding into one quick loop.
Tools you need
- Revdiff (free): a terminal app (a “TUI”, a text-based user interface that runs in your terminal instead of a separate window) that shows AI code changes and lets you annotate them.
- Claude Code (paid): the AI coding assistant that runs in your terminal and writes the code. It needs a paid Claude plan or API credits. Revdiff plugs into it to send your notes back.
Steps
-
Install Revdiff: it is an open-source command-line tool. The simplest way is to download the prebuilt file for your system (Windows, macOS, or Linux) from the project’s Releases page on GitHub. If you have the Go programming language installed, you can instead run:
go install github.com/umputun/revdiff@latestYou should be able to type
revdiffin your terminal afterwards without an error. -
Start a review from Claude Code: inside a Claude Code session, ask it to open the diff. The author shows a slash command:
/revdiff mainOr just ask in plain words:
review diff for last 3 commitsRevdiff should open as an overlay in your terminal, showing the code changes.
-
Annotate the changes: read through the diff. Drop a note on any line, any “hunk” (a connected block of changed lines), or a whole file, explaining what you want different. Press
?inside Revdiff if you are unsure of the keys; it lists them. -
Exit to send your notes: quit Revdiff when done. Your annotations are sent back to Claude Code automatically. You should see the agent acknowledge them and start revising.
-
Review the next version: Claude Code makes the changes and Revdiff reopens on the new diff, so you can keep refining in a loop until you are happy.
-
Review plans too, not just code: with the
revdiff-planningplugin, when the agent finishes a plan (it calls something namedExitPlanMode, which just means “I have a plan, here it is”), Revdiff opens on the plan text. Annotate the parts you disagree with, exit, and the agent revises the plan before writing any code, which is the cheapest time to catch a wrong approach.
Original source
Based on a Show HN post by the developer bumpa, who built Revdiff to review AI-generated code changes and plans directly inside a terminal session, integrating with AI agents like Claude Code.
Notes & variations
- Cost: Revdiff itself is free and open-source, but it is only useful alongside Claude Code, which needs a paid plan or API credits. Factor that in.
- Common pitfall: if your annotations never reach the agent, Revdiff is probably not wired into your Claude Code session correctly. Recheck the setup steps in the project README.
- Tip for better results: write annotations that say why, not just what. “Rename this for clarity” works far better than “change this”, because the AI then understands the goal and applies it consistently.