Show HN: Revdiff – 인라인 주석 기능을 갖춘 AI 에이전트용 TUI diff 리뷰어

인라인 주석 (inline annotations) 기능을 통해 diff, 파일 및 문서를 리뷰할 수 있는 TUI (Terminal User Interface)입니다. 종료 시 stdout으로 구조화된 주석을 출력하므로, 결과를 AI 에이전트 (AI agents), 스크립트 또는 기타 도구로 파이프 (pipe) 연결하기 쉽습니다.

특정 사용 사례를 위해 제작되었습니다: 터미널 기반 AI 코딩 세션 (예: Claude Code)을 벗어나지 않고 코드 변경 사항, 계획 및 문서를 리뷰하는 용도입니다. diff와 파일을 탐색하고, 특정 라인에 주석을 달고, 결과를 호출 프로세스에 반환하는 데 필요한 딱 적절한 수준의 UI만을 제공합니다. 더도 말고 덜도 말고 딱 그만큼만 제공합니다.

• stdout으로 구조화된 주석 출력 - AI 에이전트, 스크립트 또는 기타 도구로 파이프 연결 가능

• 구문 강조 (syntax highlighting)가 포함된 전체 파일 diff 뷰

• 라인 내 단어 diff (Intra-line word-diff): 추가/삭제된 쌍의 라인 내에서 변경된 특정 단어를 더 밝은 배경 오버레이로 강조합니다. 기본적으로는 꺼져 있으며, --word-diff로 활성화하거나 W로 전환할 수 있습니다.

• 축소된 diff 모드 (Collapsed diff mode): 변경 마커와 함께 최종 텍스트를 보여줍니다. v로 전환 가능

• 단어 줄 바꿈 모드 (Word wrap mode): 뷰포트 경계에서 긴 라인을 ↪ 계속됨 마커와 함께 줄 바꿈합니다. w로 전환 가능; hanging-indent 계속됨을 위한 선택 사항인 --wrap-indent N 지원 (마크다운 리스트에 유용함)

• 수평 스크롤 오버플로 표시기: 잘린 diff 라인은 화면 밖의 숨겨진 콘텐츠를 알리기 위해 가장자리에 « / » 마커를 표시합니다.

• 수직 스크롤바 썸 (Vertical scrollbar thumb): 패널 오른쪽 경계의 더 두꺼운 ┃ 세그먼트는 긴 diff, 파일 트리 및 마크다운 TOC (Table of Contents)의 가시적인 부분을 나타냅니다. 썸의 크기와 위치는 스크롤 진행 상황을 자동으로 추적합니다.

• 라인 번호: diff의 경우 이전/이후 라인 번호 거터 (gutter)를 나란히 표시하며, 전체 컨텍스트 파일의 경우 단일 열로 표시합니다. L로 전환 가능

• Mercurial 지원: hg 리포지토리를 자동 감지하고, git 스타일의 참조 (HEAD, HEAD~N)를 Mercurial revsets로 변환합니다.

• Jujutsu 지원: jj 리포지토리 (colocated git+jj 포함)를 자동 감지하고, git 스타일의 참조를 jj revsets (HEAD → @-, HEAD~N → @ 및 N+1개의 대시)로 변환합니다. --all-files가 지원됩니다.

• Blame 거터 (Blame gutter): 라인별 작성자 이름과 커밋 시기를 보여줍니다. B로 전환 가능

• diff 내의 모든 라인(추가, 삭제 또는 컨텍스트)에 주석(Annotate)을 달 수 있으며, 파일 수준의 노트(file-level notes)도 지원합니다.

• 단일 파일 자동 감지 (Single-file auto-detection): diff에 정확히 하나의 파일만 포함된 경우, 트리 창(tree pane)을 숨기고 diff 뷰에 터미널 전체 너비를 할당합니다.

• 2분할 TUI (Two-pane TUI): 파일 트리(왼쪽) + 색상이 입혀진 diff 뷰포트(오른쪽)

• Vim 스타일 (Vim-style)
  / : diff 내에서 검색
  n / N : 검색 결과 이동
  Hunk 내비게이션: 변경 그룹(change groups) 사이를 점프

• 주석 목록 팝업 (@): 파일 전체의 모든 주석을 탐색하고 원하는 주석으로 즉시 이동 - 주석이 달린 파일만 표시하도록 파일 트리 필터링 가능

• 상태 표시줄 (Status line): 파일명, diff 통계, hunk 위치, 라인 번호 및 모드 표시기 포함

• 도움말 오버레이 (?): 섹션별로 정리된 모든 키바인딩(keybindings) 표시

• 정보 팝업 (i): 실행 범위(모드, VCS, ref, 필터, 파일/상태 수, 합산 +/- 라인 통계), 선택 사항인 --description 텍스트, 그리고 현재 ref 범위 내의 모든 커밋(git/hg/jj)에 대한 커밋 로그 제목 및 본문을 표시합니다. 이는 PR 스타일의 diff를 검토할 때 서사적 맥락(narrative context)을 복원하는 데 유용합니다.

• Markdown TOC 내비게이션: 컨텍스트 전용 모드(context-only mode)에서 단일 파일 마크다운(Markdown) 파일의 경우, 헤더 내비게이션과 활성 섹션 추적 기능이 포함된 목차(table-of-contents) 창을 보여줍니다.

• 모든 파일 모드 (All-files mode): --all-files (git ls-files 또는 jj file list)를 사용하여 추적 중인 모든 파일을 탐색하고 주석을 달 수 있으며, --include 및 --exclude로 필터링할 수 있습니다.

• VCS 없는 파일 검토 (No-VCS file review): VCS 저장소 외부의 파일(또는 diff에 포함되지 않은 파일)은 --only를 통해 전체 주석 지원이 가능한 컨텍스트 전용 모드로 표시됩니다.

• 스크래치 버퍼 검토 (Scratch-buffer review): --stdin을 사용하여 파이프(piped) 또는 리다이렉션(redirected)된 임의의 텍스트에 주석을 달 수 있으며, --stdin-name으로 이름을 지정할 수 있습니다.

• Pi 패키지: pi에서 revdiff를 실행하고, 주석을 캡처하여 적용하거나 지울 때까지 위젯 및 우측 패널에 계속 표시할 수 있습니다.

• 검토 기록 (Review history): 주석과 diff를 ~/.config/revdiff/history/에 자동으로 저장합니다.

• 종료 시 안전장치로 작동

• 환경 변수(environment variables), CLI 플래그(flags), 또는 설정 파일(config file)을 통한 완전한 색상 커스터마이징 가능

• 사용자 정의 키 바인딩 (Custom keybindings): 설정 파일을 통해 모든 키를 재매핑할 수 있으며, --dump-keys를 사용하여 기본값을 내보낼 수 있습니다.

git, hg, 또는 jj (--only 또는 --stdin 사용 시 선택 사항, diff 생성에 사용됨)

Homebrew (macOS/Linux):

brew install umputun/apps/revdiff

Arch Linux (AUR):

paru -S revdiff

Debian/Ubuntu (.deb):

# GitHub Releases에서 해당 아키텍처에 맞는 최신 .deb 파일을 다운로드하세요
sudo dpkg -i revdiff_*.deb

RPM 기반 (Fedora, RHEL 등):

# GitHub Releases에서 해당 아키텍처에 맞는 최신 .rpm 파일을 다운로드하세요
sudo rpm -i revdiff_*.rpm

바이너리 릴리스 (Binary releases): GitHub Releases에서 다운로드 가능합니다 (deb, rpm, linux/darwin amd64/arm64용 아카이브).

revdiff는 Claude 세션에서 직접 대화형 코드 리뷰를 수행할 수 있도록 Claude Code 플러그인을 함께 제공합니다. 이 플러그인은 revdiff를 터미널 오버레이(overlay)로 실행하여 주석(annotations)을 캡처하고, 이를 다시 Claude에게 전달하여 처리하도록 합니다.

Claude Code 자체는 대화형 TUI 애플리케이션을 표시할 수 없기 때문에, 플러그인은 다음 터미널 중 하나가 필요합니다. 오버레이는 현재 세션 위에 별도의 터미널 레이어에서 revdiff를 실행합니다:

터미널 (Terminal)	오버레이 방식 (Overlay method)	감지 방법 (Detection)
tmux	display-popup (종료할 때까지 차단)	$TMUX 환경 변수
Zellij	zellij run --floating	$ZELLIJ 환경 변수
kitty	kitty @ launch --type=overlay	$KITTY_LISTEN_ON 환경 변수
wezterm	wezterm cli split-pane	$WEZTERM_PANE 환경 변수
Kaku	kaku cli split-pane (wezterm과 동일한 API)	$WEZTERM_PANE 환경 변수
cmux	cmux new-split + cmux send	$CMUX_SURFACE_ID 환경 변수
ghostty	AppleScript 분할 + 확대 (macOS 전용)	$TERM_PROGRAM + AppleScript 조사
iTerm2	osascript 분할 창 (macOS 전용)	$ITERM_SESSION_ID 환경 변수
Emacs vterm	emacsclient를 통한 새 프레임 생성	$INSIDE_EMACS 환경 변수

우선순위: tmux → Zellij → kitty → wezterm/Kaku → cmux → ghostty → iTerm2 → Emacs vterm (가장 먼저 감지된 것이 승리). 만약 사용 가능한 것이 없다면, 플러그인은 에러와 함께 종료됩니다.

참고: cmux는 $TERM_PROGRAM=ghostty를 함께 설정하기 때문에 ghostty보다 먼저 감지됩니다.

cmux 블록은 Ghostty의 AppleScript API 대신 cmux CLI (new-split + send --surface)를 사용합니다.

참고: iTerm2는 전체 화면 오버레이 대신 분할 창(터미널 크기에 따라 자동 감지된 수직 또는 수평 분할)을 사용합니다. iTerm2 AppleScript API는 zoom 명령어를 노출하지 않으므로, 분할 뷰는 호출한 세션과 화면 공간을 공유합니다.

참고: Ghostty 및 iTerm2 런처는 osascript (Apple Events)를 사용하며, 이는 Claude Code의 샌드박스(sandbox)에 의해 차단됩니다. 샌드박스가 활성화된 상태에서 이 터미널들을 사용한다면, Claude Code의 settings.json 내 excludedCommands에 런처를 추가하세요:

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

AppleScript 대신 CLI 도구를 사용하는 터미널(tmux, Zellij, kitty, wezterm, cmux)은 영향을 받지 않습니다.

설치:

# 마켓플레이스 추가 및 설치
/plugin marketplace add umputun/revdiff
/plugin install revdiff@revdiff

/revdiff 명령어로 사용:

/revdiff -- 스마트 감지: 커밋되지 않은 변경 사항, 마지막 커밋, 또는 브랜치 차이(diff)
/revdiff HEAD~1 -- 마지막 커밋 리뷰
/revdiff main -- main 브랜치와 현재 브랜치 비교 리뷰
...

자유 텍스트로 사용 (슬래시 명령어가 필요 없음):

"review diff" -- 스마트 감지, /revdiff와 동일
"review diff HEAD~1" -- 마지막 커밋
"review diff against main" -- 브랜치 차이(diff)
...

참조(ref)가 제공되지 않으면, 플러그인은 VCS(git, hg, 또는 jj)를 자동으로 감지하고 현재 저장소 상태를 조사하여 리뷰할 대상을 선택합니다:

• 커밋되지 않은 변경 사항이 있는 main/master 브랜치 — 커밋되지 않은 변경 사항을 리뷰합니다.
• 트리가 깨끗한(clean tree) 상태의 main/master 브랜치 — 마지막 커밋을 리뷰합니다.
• 트리가 깨끗한 상태의 기능 브랜치(feature branch) — main 브랜치에 대한 브랜치 차이(branch diff)를 리뷰합니다.
• 커밋되지 않은 변경 사항이 있는 기능 브랜치 — 커밋되지 않은 사항만 리뷰할지 또는 전체 브랜치 차이를 리뷰할지 사용자에게 묻습니다.
• VCS 저장소 외부 — 무엇을 리뷰할지 사용자에게 묻는 방식으로 대체됩니다.

이 플러그인에는 내장된 참조 문서(reference documentation)가 포함되어 있어 revdiff 사용법, 사용 가능한 테마, 키 바인딩(keybindings) 및 설정 옵션에 관한 질문에 답할 수 있습니다. 또한 요청 시 로컬 설정 파일(~/.config/revdiff/config)을 생성하거나 수정할 수 있습니다:

"revdiff는 어떤 chroma 테마를 지원하나요?"
"revdiff를 dracula 테마로 전환해줘"
"revdiff의 키 바인딩은 무엇인가요?"
...

이 플러그인은 전체 리뷰 루프(review loop)를 지원합니다: 주석 달기(annotate) → 계획(plan) → 수정(fix) → 더 이상 주석이 남지 않을 때까지 재리뷰(re-review).

커스텀 런처(Custom launchers): 두 Claude 플러그인 모두 런처 스크립트를 2단계 체인(사용자 → 번들)을 통해 해결하므로, 플러그인을 포크(fork)하지 않고도 ${CLAUDE_PLUGIN_DATA}/scripts/launch-revdiff.sh에 커스텀 런처를 배치할 수 있습니다. 설계상 프로젝트 수준(.claude/...)의 오버라이드(override) 레이어는 존재하지 않습니다. 이는 플래닝 훅(planning hook)이 모든 ExitPlanMode에서 자동으로 실행되기 때문이며, 저장소 제어 실행 파일 레이어가 있다면 신뢰할 수 없는 저장소가 일반적인 Claude 작업 중에 임의의 코드를 실행할 수 있기 때문입니다. diff-review 스킬에 대해서는 .claude-plugin/skills/revdiff/references/install.md를, 플래닝 훅에 대해서는 plugins/revdiff-planning/README.md를 참조하십시오.

별도의 revdiff-planning 플러그인은 Claude가 계획 모드(plan mode)를 종료할 때 자동으로 revdiff를 열어주어, 승인하기 전에 계획에 주석을 달 수 있게 해줍니다. 주석을 추가하면 Claude가 계획을 수정하고 다시 요청하며, 사용자가 만족할 때까지 이 루프가 반복됩니다.

/plugin install revdiff-planning@revdiff

이 플러그인은 메인 revdiff 플러그인과 독립적이며 다른 플래닝 플러그인(예: cc-thingz의 planning)과 충돌하지 않습니다.

revdiff는 또한 pi 패키지로도 제공됩니다. 이 확장 기능은 기존의 revdiff 바이너리 (binary)를 실행하고, 종료 시 주석 (annotations)을 캡처하여, pi 내부에서 지속적인 위젯 (widget) 및 우측 결과 패널 형태로 렌더링합니다.

설치 (Install):

pi install https://github.com/umputun/revdiff

pi 내부 명령어 (Commands inside pi):

/revdiff -- 커밋되지 않은 변경 사항, 스테이징된 (staged) 변경 사항 또는 브랜치 변경 사항을 감지한 후 revdiff를 실행
/revdiff HEAD~1 -- 마지막 커밋 리뷰
/revdiff --all-files -- 모든 추적된 파일 탐색
...

참고 사항 (Notes):

• PATH에 revdiff 바이너리가 필요합니다.
• pi가 바이너리를 찾을 수 없는 경우 REVDIFF_BIN=/absolute/path/to/revdiff를 설정하세요.
• 동일 터미널 모드 (Same-terminal mode)가 기본값입니다: pi가 일시적으로 중단되고, revdiff가 터미널을 제어하며, 종료 시 pi가 다시 재개됩니다.
• 선택 사항인 오버레이 모드 (--pi-overlay 또는 REVDIFF_PI_MODE=overlay)는 Claude 플러그인 통합에서 사용되는 기존 launch-revdiff.sh 스크립트를 재사용합니다. pi는 번들된 스크립트를 직접 호출하며 Claude 플러그인의 오버라이드 (overrides)를 따르지 않습니다 (pi 런타임에서 CLAUDE_PLUGIN_DATA가 설정되지 않음).
• 선택 사항인 편집 후 알림 (post-edit reminders)은 /revdiff-reminders on을 통해 사용할 수 있으며, 에이전트가 편집한 후 /revdiff 또는 /revdiff-rerun을 실행하도록 제안합니다.
• 저장소 내에서 pi 전용 리소스는 하네스 (harness) 통합을 명확하게 분리하기 위해 plugins/pi/ 아래에 위치합니다.

revdiff는 Codex 세션에서 직접 대화형 diff 리뷰 및 플랜 주석 (plan annotation)을 수행할 수 있는 Codex CLI 플러그인을 함께 제공합니다. 이 플러그인은 두 가지 스킬 (skills)을 제공합니다:

/revdiff — Claude Code 플러그인과 동일한 diff 리뷰 워크플로우 (참조 감지, 오버레이 실행, 주석 캡처, 피드백 루프)
/revdiff-plan — 세션 롤아웃 (rollout) 파일에서 마지막 Codex 어시스턴트 메시지를 추출하여 revdiff에서 주석을 달 수 있도록 열고, 피드백을 다시 전달

이 플러그인은 Claude Code 플러그인과 동일한 터미널 오버레이 메커니즘 (tmux, Zellij, kitty, wezterm 등)을 사용합니다.

설치 (Install):

# 먼저 저장소를 클론하세요
git clone https://github.com/umputun/revdiff.git
cd revdiff
...

요구 사항 (Requirements):

• PATH에 revdiff 바이너리
• jq

(/revdiff-plan 세션 추출에 필요)

• 오버레이 모드 (overlay mode)를 지원하는 터미널 멀티플렉서 (terminal multiplexer) 중 하나

참고 사항 (Notes):

• Codex에는 훅 (hook) 시스템이 없습니다 — 계획 검토 (plan review)를 위해서는 Codex가 계획을 생성한 후 수동으로 /revdiff-plan을 호출해야 합니다.
• 스크립트는 Claude Code 플러그인에서 가져온 이식 가능한 복사본이며, 심볼릭 링크 (symlink)가 아닙니다.
• 플러그인 소스는 저장소 내 plugins/codex/에 위치합니다.

revdiff는 도구 (tool), 슬래시 명령어 (slash command), 그리고 계획 검토 (plan-review) 플러그인을 통해 OpenCode와 통합됩니다. 이 도구는 기존의 launch-revdiff.sh 런처 (launcher)를 래핑 (wrap)하므로, 터미널 감지 (terminal detection)가 자동으로 동기화된 상태를 유지합니다.

설치 (Install):

cd plugins/opencode && bash setup.sh

설치 스크립트는 파일들을 ~/.config/opencode/로 복사하고 plan-review 플러그인을 등록합니다. 수동 설치 및 자세한 내용은 plugins/opencode/README.md를 참조하세요.

OpenCode 내부 명령어 (Commands inside OpenCode):

/revdiff -- revdiff TUI로 git diff 검토
/revdiff HEAD~3 -- 최근 3개의 커밋 검토

plan-review 플러그인은 어시스턴트 (assistant)가 계획 모드 (plan mode)를 종료할 때 자동으로 revdiff를 실행하여, 승인하기 전에 주석 (annotate)을 달 수 있게 해줍니다.

구조화된 표준 출력 (stdout) 결과는 텍스트를 읽을 수 있는 모든 도구와 함께 작동합니다:

# 처리를 위한 주석 캡처
annotations=$(revdiff main)
if [ -n "$annotations" ]; then
...

revdiff [OPTIONS] [base] [against]