revdiff: a diff reviewer that hands its annotations back to the agent

Annotations on stdout, not in a web form

revdiff is a TUI for reviewing diffs, files and documents with inline annotations, and the design goal is stated plainly: it outputs structured annotations to stdout on quit, which makes it easy to pipe results into AI agents, scripts or other tools. That is the whole point of the project, and it explains why the README describes it as built for a specific use case, reviewing code changes, plans and documents without leaving a terminal-based AI coding session such as Claude Code, with just enough UI to move through diffs and files, annotate specific lines and return the results to the calling process. The alternative workflow, a reviewer typing comments into a pull request form, has no machine-readable output at all. Here the reviewer marks a line, adds a note, quits, and the calling process receives a machine-readable account of what was flagged. The repository topics reflect the same audience, listing agentic-workflow, claude-code and code-review alongside diff and tui.

Two panes, a single-file shortcut and a large keybinding set

The interface is a two-pane TUI with a file tree on the left and a colorized diff viewport on the right. When the diff contains exactly one file, the tree pane hides and the diff takes the full terminal width, which is a small detail that decides whether the tool feels cramped. Syntax highlighting is built in, and the README lists a set of focused behaviours rather than a general purpose viewer. Word wrap toggles with w and can be given a hanging indent with --wrap-indent N for markdown lists. Collapsed diff mode toggles with v and shows the final text with change markers instead of both sides. Intra-line word diff highlights the specific changed words inside paired added and removed lines using a brighter background overlay, off by default and enabled with --word-diff or the W key. Line numbers toggle with L, the blame gutter showing author and commit age toggles with B, the annotation list opens with @, the help overlay with ? and the info popup with i. Search uses a vim-style slash with n and N to move between matches, and hunk navigation jumps between change groups.

Git, Mercurial and Jujutsu, with a version trap on blame

revdiff detects the version control system rather than assuming git. Mercurial repositories are detected automatically, and git-style refs such as HEAD and HEAD~N are translated into Mercurial revsets. Jujutsu repositories are detected too, including colocated git and jj checkouts, where git-style refs are translated into jj revsets, with HEAD becoming @- and HEAD~N becoming @ plus N+1 dashes. There is one hard dependency to note. The README states that Jujutsu must be 0.27 or newer, because versions 0.23 through 0.26 have no jj file annotate -T, which means the blame gutter does not work, and versions before 0.23 also reject the commit log template behind the commit info popup. Git-specific features still exist alongside this: renamed files show their origin in the diff pane header as old to new and render only the real line changes rather than a full delete and add, which keeps a review readable when a file has been moved.

Reviewing piped diffs without a repository

Two flags let revdiff work on content that is not in your working tree. The --only flag shows files outside a VCS repo, or files not covered by any diff, as context-only with full annotation support. The --stdin flag reads arbitrary piped or redirected text, and --stdin-name names it. The behaviour then depends on what arrives: when the piped content sniffs as a git unified diff, revdiff parses it as a real multi-file diff, so the output of gh pr diff or git format-patch -1 --stdout can be reviewed directly, and otherwise the input is shown as a single context-only buffer. That is the interesting part of the design, because a pipeline that produces a patch can hand it straight to revdiff without a checkout. There is also an all-files mode, --all-files, which browses and annotates all tracked files using git ls-files or the jj file list, filterable with --include and --exclude, and single-file markdown documents in context-only mode get a table of contents pane with header navigation and active section tracking.

Installing the binary

There are packages for the usual platforms. On macOS and Linux with Homebrew:

brew install umputun/apps/revdiff

On Arch with the AUR:

paru -S revdiff

On Debian and Ubuntu, downloading the .deb for your architecture from GitHub Releases:

# download the latest .deb for your architecture from GitHub Releases
sudo dpkg -i revdiff_*.deb

and the RPM equivalent for Fedora and RHEL style systems:

# download the latest .rpm for your architecture from GitHub Releases
sudo rpm -i revdiff_*.rpm

If you have Go installed, the binary comes from the module path, and the command installs revdiff into GOBIN, which defaults to the bin directory of your GOPATH, so that directory has to be on your PATH:

go install github.com/umputun/revdiff/app/revdiff@latest

Prebuilt archives for linux and darwin on amd64 and arm64 are also published on GitHub Releases. The module itself requires Go 1.26.0, and the terminal stack comes from the Charm libraries, with bubbletea for the runtime, lipgloss for styling and bubbles for the widgets, alongside chroma for syntax highlighting and go-flags for the command line parsing.

The agent plugin depends on what your terminal can do

revdiff ships a Claude Code plugin for interactive review inside a Claude session. The plugin launches revdiff as a terminal overlay, captures the annotations and feeds them back to Claude. The constraint is the interesting part, and the README states it plainly: Claude Code itself cannot display interactive TUI applications, so the overlay runs revdiff in a separate terminal layer on top of the current session. The plugin therefore requires a terminal that supports overlays, with agterm detected through the AGTERM_SESSION_ID environment variable and a tmux display-popup approach as the other option. A team whose terminal cannot host an overlay gets the standalone tool and the piped output, but not the in-session review loop. There is also a pi package, revdiff-pi, which launches revdiff from pi, captures the annotations and sends them to the agent immediately. Annotations and diffs are auto-saved to ~/.config/revdiff/history/ on quit as a safety net, colours are configurable through environment variables, command line flags or a config file, and any key can be remapped in a config file, with the defaults exportable through --dump-keys.

Editorial conclusion

revdiff fits a team that drives coding agents from the terminal and wants a human in the loop who can mark the exact line that matters, and it fits reviewers who prefer a keyboard-driven diff viewer over a web UI. It does not fit a workflow that expects annotations to be stored in a hosted review system, and it does not fit a machine without git, hg or jj unless you only use the --only or --stdin paths. Verify first that your terminal can host an overlay if you plan to use the Claude Code plugin, since the README says the plugin needs agterm or tmux because Claude Code cannot display an interactive TUI itself. The licence field on the repository says MIT, and the last push was on 2026-10-18 with release v1.13.0 published on 2026-09-05.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. umputun/revdiff on GitHub