revdiff-planning

 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
• 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
• Line numbers: side-by-side old/new line number gutter, toggle with L
• 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
• 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 git-tracked files with --all-files, filter with --exclude
• No-git file review: --only files outside a git repo (or not in any diff) are shown as context-only with full annotation support
• 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 (used to generate diffs; optional when using --only for standalone file review)

Installation

Homebrew (macOS/Linux):

brew install umputun/apps/revdiff

Go install:

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

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:

Terminal	Overlay method	Detection
tmux	display-popup (blocks until quit)	$TMUX env var
kitty	kitty @ launch --type=overlay	$KITTY_LISTEN_ON env var
wezterm	wezterm cli split-pane	$WEZTERM_PANE env var
ghostty	AppleScript split + zoom (macOS only)	$TERM_PROGRAM + AppleScript probe
iTerm2	osascript split pane (macOS only)	$ITERM_SESSION_ID env var
Emacs vterm	New frame via emacsclient	$INSIDE_EMACS env var

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

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.

Install:

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

Use with /revdiff command: