/revdiff

name: revdiff
description: Review diffs, files, and documents with inline annotations in a TUI overlay, or answer questions about revdiff usage, configuration, themes, and keybindings. Opens revdiff in agterm/tmux/zellij/herdr/kitty/wezterm/kaku/cmux/ghostty/iterm2/emacs-vterm, captures annotations, and addresses them. Works in git, hg, and jj repos (auto-detected). Activates on "revdiff", "review diff", "review changes", "annotate diff", "git review with revdiff", "hg review with revdiff", "review jj change", "interactive diff review", "revdiff all files", "review all files", "browse all files", "revdiff FILE", "revdiff README.md", "revdiff /tmp/notes.txt", "review this file", "annotate this file", "review file with revdiff", "open this review in revdiff", "show review in revdiff", "review in revdiff", "revdiff config", "revdiff themes", "revdiff keybindings", "how to configure revdiff", "what themes does revdiff have".

revdiff - TUI Diff Review

Review diffs with inline annotations using revdiff TUI in a terminal overlay. Works in git, hg, and jj repos (auto-detected).

Script Path Resolution

Resolve `<plugin-root>` from this skill's absolute path in the available-skills catalogue. It is the directory containing this plugin's `.codex-plugin/plugin.json`. Then set:

SCRIPT_DIR="<plugin-root>/skills/revdiff/scripts"

Replace `<plugin-root>` with the resolved absolute path before running the command. Use `$SCRIPT_DIR` in place of script paths throughout this skill.

**Note**: the launcher override chain (user via `${CLAUDE_PLUGIN_DATA}` → bundled) is Claude-only. Codex users can customize the launcher in a local marketplace checkout and reinstall the plugin.

Activation Triggers

• "revdiff", "review diff", "review changes", "annotate diff"
• "revdiff HEAD~1", "revdiff main"
• "hg review with revdiff", "review jj change"
• "revdiff all files", "review all files", "browse all files"
• "revdiff all files exclude vendor"
• "revdiff README.md", "revdiff docs/plan.md", "revdiff /tmp/notes.txt" — single-file review (`--only` mode)
• "review this file", "annotate this file", "review file with revdiff"
• "open this review in revdiff", "show review in revdiff", "review in revdiff" — open an in-session review (preload mode)

Answering Questions

If the user asks a question about revdiff (configuration, themes, keybindings, installation, usage) rather than requesting a review session, consult the reference files in `references/` and answer directly. Do NOT launch the TUI for informational questions.

• `references/install.md` — installation methods and plugin setup
• `references/config.md` — config file, options, colors, chroma themes
• `references/usage.md` — examples, key bindings, output format

Using Existing Review History

If the user says things like "locate my review", "use my latest revdiff annotations", "pull up the review I just did in another terminal", or "what did I annotate earlier" — the user ran revdiff outside this plugin flow and wants Codex to process the stored annotations. Read the most recent file from the persistent history directory via the helper script, then process the annotations through Step 3.5 classification as if they had come from a fresh launcher call:

$SCRIPT_DIR/read-latest-history.sh

The script resolves the history dir from `$REVDIFF_HISTORY_DIR` (default `~/.config/revdiff/history`), finds the repo subdir via VCS root basename (jj/git/hg), and prints the newest `.md` file whose `path:` header names the current checkout (a directory header must equal the repo root; a single-file `--only` header without git matches when the file sits directly in the root). Each history file contains a header (path, refs, and — when available — a git commit hash), the annotations in `## file:line (type)` format, and the raw git diff for annotated files. The `commit:` line and diff block are captured from git only; in hg/jj repos the diff block will be empty and no commit hash is recorded. See `references/usage.md` "Review History" section for directory layout, stdin/only handling, and override options.

The history file is also the recovery path when a review is cut short by a lost connection: on signal termination (a SIGHUP from a dropped SSH/tmux client, or a SIGTERM) revdiff saves the current annotations to history — never the `-o` output — so `read-latest-history.sh` still recovers them.

Opening an In-Session Review

When the user asks to open an in-session review in revdiff (the conversation already contains review comments produced earlier in the session), write those comments to a temp file (e.g. `/tmp/revdiff-review-XXXXXX.md`) using the format documented in `references/usage.md` ("Output Format" section), then run the normal launcher flow (Step 1 ref detection, Step 2 invocation) with `--annotations=<temp-path>` appended. Step 3 onward handles the curated annotations as usual.

Reviewing a Diff That Lives Outside the Working Tree

Some review targets are not the current repo state: a GitHub PR diff, a patch file on disk, or `git format-patch -1 --stdout` output. Pipe the unified diff into `revdiff --stdin` and the input is parsed as a real multi-file diff (one tree entry per file, hunk navigation, per-file annotations) instead of a context-only buffer. revdiff auto-detects the unified-diff signature; on a malformed patch the input falls back silently to raw-text mode.

Use this instead of the normal launcher flow when:

• the user asks to "review PR #N", "review this patch", "review `gh pr diff` output", or supplies a patch URL/path
• the diff describes commits that are not checked out locally (e.g. someone else's branch on a remote-only PR)
• the user pastes a unified diff and asks for a review of *that diff*, not the working tree

Example invocations (route through the same launcher as the normal flow):

gh pr diff 123 | $SCRIPT_DIR/launch-revdiff.sh --stdin
git format-patch -1 --stdout | $SCRIPT_DIR/launch