Documentation

Complete reference for revdiff usage, configuration, themes, keybindings, the pi package, and the Claude Code plugin.

Requirements

git is used to generate diffs. It is optional when using --only for standalone file review or --stdin for scratch-buffer review.

Installation

Homebrew (macOS/Linux)

Binary releases

Download from GitHub Releases — deb, rpm, archives for linux/darwin amd64/arm64.

Pi package

revdiff also ships as a pi package. The extension launches the existing revdiff binary, captures annotations on exit, and keeps them visible inside pi as a persistent widget plus a right-side results panel.

Commands inside pi

Requires the revdiff binary on PATH. Set REVDIFF_BIN=/absolute/path/to/revdiff if pi can’t find the binary. Same-terminal mode is the default. Optional overlay mode (--pi-overlay or REVDIFF_PI_MODE=overlay) reuses the existing launch-revdiff.sh script from the Claude plugin integration. Optional post-edit reminders (/revdiff-reminders on) suggest running /revdiff or /revdiff-rerun after agent edits.

Usage

Positional arguments support several forms:

• revdiff — uncommitted changes
• revdiff HEAD~3 — diff a single ref against the working tree
• revdiff main feature — diff between two refs
• revdiff main..feature — same as above, git dot-dot syntax
• revdiff main...feature — changes since feature diverged from main

Examples

All-files mode

Use --all-files (or -A) to browse all git-tracked files, not just files with changes. This turns revdiff into a general-purpose code annotation tool. All files are shown in context-only mode with full annotation and syntax highlighting support.

--all-files requires a git repository (uses git ls-files) and is mutually exclusive with refs, --staged, and --only. Combine with --exclude (or -X) to filter by prefix.

--exclude uses prefix matching: --exclude vendor skips vendor/, vendor/foo.go, etc. It works in both --all-files and normal diff modes.

Persist in config: exclude = vendor. Or env: REVDIFF_EXCLUDE=vendor,mocks.

Context-only file review

When --only specifies a file that has no git changes (or when no git repo exists), revdiff shows the file in context-only mode: all lines displayed without +/- markers, with full annotation and syntax highlighting support.

• Inside a git repo — files not in the diff are read from disk alongside changed files
• Outside a git repo — --only is required; files are read directly from disk

Scratch-buffer review

Use --stdin to review arbitrary piped or redirected text as a single synthetic file. All lines are treated as context, so the normal single-file review flow still works: annotations, file-level notes, search, wrap, collapsed mode, and structured output.

--stdin is explicit, requires piped or redirected input, and is mutually exclusive with refs, --staged, --only, --all-files, and --exclude.

Use --stdin-name to control the synthetic filename for annotation output and extension-based highlighting or markdown TOC activation.

Markdown TOC navigation

When reviewing a single markdown file in context-only mode, a table-of-contents pane appears on the left listing all markdown headers. This works for --only files and for --stdin when --stdin-name ends with .md or .markdown. Use Tab to switch focus, j/k to navigate, Enter to jump. The TOC highlights the current section as you scroll. Headers inside fenced code blocks are excluded.

Beyond code review

The --only and --stdin flags enable use cases beyond git diffs. Files and ephemeral command output can both be loaded for annotation, no git repo required.

Reviewing AI-generated drafts — When an AI assistant drafts text to be posted publicly (PR comments, issue responses, release notes), write it to a temp file and review in revdiff. Annotate specific lines, the assistant rewrites, re-open to verify.

Reviewing documentation and specs — Markdown files, API specs, config files, and plan documents can all be reviewed with inline annotations.

Reviewing generated output — CI configs, Terraform plans, generated migrations — anything that needs human review before being applied.

Config file

Location: ~/.config/revdiff/config (INI format). Override with --config flag or REVDIFF_CONFIG env var.

Precedence: CLI flags > env vars > config file > built-in defaults.

Options

Themes

Five bundled color themes: catppuccin-mocha, dracula, gruvbox, nord, and solarized-dark. Stored in ~/.config/revdiff/themes/, auto-created on first run.

Set default in config: theme = dracula. Or env: REVDIFF_THEME=dracula.

Creating custom themes

Two approaches:

1. From current colors: customize individual colors via config or --color-* flags, then dump: revdiff --dump-theme > ~/.config/revdiff/themes/my-custom
2. From scratch: copy a bundled theme and edit directly. Each file defines all 21 color keys plus chroma-style in INI format:

Precedence

Without --theme: built-in defaults → config file → env vars → CLI flags.

When --theme is set, it takes over completely: all 21 color fields and chroma-style are overwritten, ignoring any --color-* flags or env vars. --theme + --no-colors prints a warning and applies the theme.

Color customization

All color options accept hex values (#rrggbb) and have REVDIFF_COLOR_* env vars.

Chroma syntax highlighting styles

Set via --chroma-style, env REVDIFF_CHROMA_STYLE, or config chroma-style = name.

Dark themes

aura-theme-dark, aura-theme-dark-soft, base16-snazzy, catppuccin-frappe, catppuccin-macchiato (default), catppuccin-mocha, doom-one, doom-one2, dracula, evergarden, fruity, github-dark, gruvbox, hrdark, monokai, modus-vivendi, native, nord, nordic, onedark, paraiso-dark, rose-pine, rose-pine-moon, rrt, solarized-dark, solarized-dark256, tokyonight-moon, tokyonight-night, tokyonight-storm, vim, vulcan, witchhazel, xcode-dark

Light themes

autumn, borland, catppuccin-latte, colorful, emacs, friendly, github, gruvbox-light, igor, lovelace, manni, modus-operandi, monokailight, murphy, paraiso-light, pastie, perldoc, pygments, rainbow_dash, rose-pine-dawn, solarized-light, tango, tokyonight-day, trac, vs, xcode

Other

RPGLE, abap, algol, algol_nu, arduino, ashen, average, bw, hr_high_contrast, onesenterprise, swapoff

Navigation

Search

Annotations

View toggles

Custom keybindings

All keybindings can be customized via ~/.config/revdiff/keybindings. Override path with --keys or REVDIFF_KEYS.

Generate a template: revdiff --dump-keys > ~/.config/revdiff/keybindings

Modal keys (annotation input, search input, confirm discard) are not remappable.

Available actions

Navigation: down, up, page_down, page_up, half_page_down, half_page_up, home, end, scroll_left, scroll_right

File/Hunk: next_item, prev_item, next_hunk, prev_hunk

Pane: toggle_pane, focus_tree, focus_diff

Search: search

Annotations: confirm, annotate_file, delete_annotation, annot_list

View: toggle_collapsed, toggle_wrap, toggle_tree, toggle_line_numbers, toggle_hunk, filter

Quit: quit, discard_quit, help, dismiss

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.

Terminal support

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: tmux → zellij → kitty → wezterm/kaku → cmux → ghostty → iTerm2 → Emacs vterm (first detected wins). cmux is checked before ghostty because it also sets $TERM_PROGRAM=ghostty. iTerm2 uses a split pane rather than a full-screen overlay.

Plugin usage

Slash commands

Natural language

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

The plugin supports the full review loop: annotate → plan → fix → re-review until no more annotations remain.

Auto-detection

When no ref is provided, the plugin detects what to review automatically:

• 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

Plan review plugin

A separate revdiff-planning plugin automatically opens revdiff when Claude exits plan mode, letting you annotate the plan before approving it. If you add annotations, Claude revises the plan and asks again, looping until you're satisfied.

This plugin is independent from the main revdiff plugin and does not conflict with other planning plugins.

Output format

On quit, revdiff outputs annotations to stdout (or file via --output):

Each annotation block: ## filename:line[-end] (type) where type is (+) added, (-) removed, or (file-level); -end is included when the annotation covers a line range.

When annotation text contains the keyword “hunk” (case-insensitive, whole word), the output header automatically expands to include the full hunk line range (e.g., handler.go:43-67 (+) instead of handler.go:43 (+)). This gives AI consumers the range context without any extra steps.

Integration with other tools

The structured stdout output works with any tool that can read text: