revdiff  

TUI for reviewing diffs, files, and documents with inline annotations. Outputs structured annotations to stdout on quit, making it easy to pipe results into AI agents, scripts, or other tools.

Built for a specific use case: reviewing code changes, plans, and documents without leaving a terminal-based AI coding session (e.g., Claude Code). Just enough UI to navigate diffs and files, annotate specific lines, and return the results to the calling process - no more, no less.

Features

• Structured annotation output to stdout - pipe into AI agents, scripts, or other tools
• Full-file diff view with syntax highlighting
• Intra-line word-diff: highlights the specific changed words within paired add/remove lines using a brighter background overlay, off by default — enable with --word-diff or toggle with W
• Collapsed diff mode: shows final text with change markers, toggle with v
• Word wrap mode: wraps long lines at viewport boundary with ↪ continuation markers, toggle with w; optional --wrap-indent N for hanging-indent continuations (handy for markdown lists)
• Horizontal scroll overflow indicators: truncated diff lines show « / » markers at the edges to signal hidden content off-screen
• Vertical scrollbar thumb: a thicker ┃ segment on pane right borders indicates the visible portion of long diffs, file trees, and markdown TOCs; thumb size and position track scroll progress automatically
• Line numbers: side-by-side old/new line number gutter for diffs, single column for full-context files, toggle with L
• Rename-aware diffs (git): a renamed file shows its origin in the diff-pane header as old → new and renders only the real line changes instead of a full delete-and-add
• Mercurial support: auto-detects hg repos, translates git-style refs (HEAD, HEAD~N) to Mercurial revsets
• Jujutsu support: auto-detects jj repos (including colocated git+jj), translates git-style refs to jj revsets (HEAD → @-, HEAD~N → @ plus N+1 dashes); --all-files supported
• Blame gutter: shows author name and commit age per line, toggle with B
• Annotate any line in the diff (added, removed, or context) plus file-level notes
• Single-file auto-detection: when a diff contains exactly one file, hides the tree pane and gives full terminal width to the diff view
• Two-pane TUI: file tree (left) + colorized diff viewport (right)
• Vim-style / search within diff with n/N match navigation
• Hunk navigation to jump between change groups
• Annotation list popup (@): browse all annotations across files, jump to any annotation
• Filter file tree to show only annotated files
• Status line with filename, diff stats, hunk position, line number, and mode indicators
• Help overlay (?) showing all keybindings organized by section
• Info popup (i) showing launch scope (mode, VCS, ref, filters, file/status counts, aggregate +/- line stats), the optional --description prose, and the commit log subject + body for every commit in the current ref range (git/hg/jj) — useful for restoring narrative context when reviewing PR-style diffs
• Markdown TOC navigation: single-file markdown files in context-only mode show a table-of-contents pane with header navigation and active section tracking
• All-files mode: browse and annotate all tracked files with --all-files (git ls-files or jj file list), filter with --include and --exclude
• No-VCS file review: --only files outside a VCS repo (or not in any diff) are shown as context-only with full annotation support
• Scratch-buffer review: annotate arbitrary piped or redirected text with --stdin, optionally naming it with --stdin-name. When the piped content sniffs as a git unified diff, revdiff parses it as a real multi-file diff (review gh pr diff or git format-patch -1 --stdout output directly); otherwise the input is shown as a single context-only buffer.
• Pi package: launch revdiff from pi, capture annotations, and send them to the agent immediately for the normal review loop
• Review history: auto-saves annotations and diffs to ~/.config/revdiff/history/ on quit as a safety net
• Fully customizable colors via environment variables, CLI flags, or config file
• Custom keybindings: remap any key via config file, export defaults with --dump-keys

Requirements

• git, hg, or jj (used to generate diffs; optional when using --only or --stdin)

Installation

Homebrew (macOS/Linux):

brew install umputun/apps/revdiff

Arch Linux (AUR):

paru -S revdiff

Debian/Ubuntu (.deb):

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

RPM-based (Fedora, RHEL, etc.):

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

Binary releases: download from GitHub Releases (deb, rpm, archives for linux/darwin amd64/arm64).

Claude Code Plugin

revdiff ships with a Claude Code plugin for interactive code review directly from a Claude session. The plugin launches revdiff as a terminal overlay, captures annotations, and feeds them back to Claude for processing.

The plugin requires one of the following terminals since Claude Code itself cannot display interactive TUI applications - the overlay runs revdiff in a separate terminal layer on top of the current session:

Priority: agterm → tmux → Zellij → herdr → kitty → wezterm/Kaku → cmux → ghostty → iTerm2 → Emacs vterm (first detected wins). If none are available, the plugin exits with an error.

Note: cmux is detected before ghostty when $CMUX_SURFACE_ID is set, __CFBundleIdentifier=com.cmuxterm.app, or GHOSTTY_RESOURCES_DIR / GHOSTTY_BIN_DIR contains cmux.app. The cmux block uses the cmux CLI (new-split + send --surface) instead of Ghostty's AppleScript API.

Note: iTerm2 uses a split pane (vertical or horizontal, auto-detected from terminal dimensions) rather than a full-screen overlay. The iTerm2 AppleScript API does not expose a zoom command, so the split view shares screen space with the invoking session.

Note: Ghostty and iTerm2 launchers use osascript (Apple Events), which is blocked by Claude Code's sandbox. If you use these terminals with sandbox enabled, add the launcher to excludedCommands in your Claude Code settings.json:

{
  "permissions": {
    "excludedCommands": ["*/launch-revdiff.sh*"]
  }
}

Terminals that use CLI tools instead of AppleScript (agterm, tmux, Zellij, herdr, kitty, wezterm, Kaku, cmux) are not affected.

Install:

# add marketplace and install
/plugin marketplace add umputun/revdiff
/plugin install revdiff@revdiff

Use with /revdiff command:

/revdiff                  -- smart detection: uncommitted, last commit, or branch diff
/revdiff HEAD~1           -- review last commit
/revdiff main             -- review current branch against main
/revdiff --staged         -- review staged changes only
/revdiff HEAD~3           -- review last 3 commits

Use with free text (no slash command needed):

"review diff"                     -- smart detection, same as /revdiff
"review diff HEAD~1"              -- last commit
"review diff against main"        -- branch diff
"review changes from last 2 days" -- Claude resolves the ref automatically
"revdiff for staged changes"      -- staged only

When no ref is provided, the plugin auto-detects the VCS (git, hg, or jj) and inspects the current repo state to pick what to review:

• On main/master with uncommitted changes — reviews uncommitted changes
• On main/master with clean tree — reviews the last commit
• On a feature branch with clean tree — reviews branch diff against main
• On a feature branch with uncommitted changes — asks whether to review uncommitted only or the full branch diff
• Outside a VCS repo — falls back to asking the user what to review

The plugin includes built-in reference documentation and can answer questions about revdiff usage, available themes, keybindings, and configuration options. It can also create or modify the local config file (~/.config/revdiff/config) on request:

"what chroma themes does re