Hunk

review-first terminal diff viewer — OpenTUI × Pierre diffs · hunkdiff 0.17

1 — 概要
何をするか

Hunk（npm: hunkdiff）は、エージェントが書いた変更一式をレビュー優先の UI で読むためのターミナル diff ビューア。UI 基盤は OpenTUI、差分表示は Pierre diffs を利用する。リポジトリは modem-dev/hunk。

Multi-fileサイドバー付きストリーム
InlineAI / エージェント注釈
VCSGit / jj / Sapling
Watchファイル・作業ツリー追従
  • キーボード・マウス・pager・Git difftool との連携
  • 未追跡ファイルを含むワーキングツリーのレビュー（hunk diff）
  • 任意コミット / revset、パッチ stdin、2 ファイル比較
  • split / stack / 自動レイアウト、テーマセレクタ（t）
2 — インストールと要件
グローバル CLI 
npm i -g hunkdiff

# または Homebrew
brew install hunk
Homebrew 移行: 以前 modem-dev/tap から入れていた場合は、先に brew uninstall modem-dev/tap/hunk してから公式 formula を入れる。
  • Node.js 18 以上
  • macOS、Linux、または Windows
  • 多くのワークフローで Git を推奨（jj / Sapling も自動検出）
  • Nix 利用者は flake.nix の default パッケージ（詳細は上流 nix/README.md）
hunk           # ヘルプ
hunk --version # バージョン表示
3 — VCS・ファイル・パッチ
Git

サブコマンドは Git の diff 系に寄せており、結果をプレーン text ではなくレビュー UI に載せる。

hunk diff                      # 現在の変更（未追跡含む）
hunk diff --watch              # ワーキングツリー変更で自動再読込
hunk show                      # 最新コミット
hunk show HEAD~1               # 過去コミット
Jujutsu / Sapling

jj または Sapling のチェックアウトを自動検出する。hunk diff [revset] / hunk show [revset] はネイティブ revset を使う。検出を上書きするときは設定で vcs = "git" / "jj" / "sl" を指定する。

2 ファイル比較とパッチ 
hunk diff before.ts after.ts
hunk diff before.ts after.ts --watch
git diff --no-color | hunk patch -
4 — エージェント連携
ライブセッション（推奨）
  1. 別ターミナルで hunk diff または hunk show を起動する。
  2. hunk skill path が返すスキルパスをエージェントに読ませる（同梱 skills/hunk-review/SKILL.md）。
  3. ライブセッション向けにスキルを実行させる。
Load the Hunk skill and use it for this review.
Run `hunk skill path` to get the skill path.

TUI 起動時にローカル loopback デーモンへ登録され、hunk session ... でウィンドウを操作する。よく使う例:

hunk session list
hunk session get --repo .
hunk session review --repo . --json
hunk session navigate --repo . --file src/App.tsx --hunk 2
hunk session reload --repo . -- diff
代替: 事前に書いた注釈を --agent-context で読み込む方法もある。手順の全文は上流の docs/agent-workflows.md。
5 — 他ツールとの機能比較（要約）
README 掲載マトリクスの抜粋
能力 Hunk lumen delta difftastic GNU diff
レビュー優先の対話 UI○○×××
複数ファイルストリーム + サイドバー○○×××
インライン エージェント / AI 注釈○××××
自動 split / stack レイアウト○××××
ビューア内マウス操作○○×××
構造 diff（トークン単位）×××○×
pager 互換モード○×○○○
シンタックス強調○○○○×

全文の比較表（diff-so-fancy 等）は modem-dev/hunk の README を参照。

6 — 設定ファイル
永続化の場所
  • ~/.config/hunk/config.toml
  • リポジトリ直下の .hunk/config.toml

例（TOML）

theme = "github-dark-default" # 組み込み id / auto / custom
mode = "auto"        # auto, split, stack
vcs = "git"          # git, jj, sl
watch = false
exclude_untracked = false
line_numbers = true
wrap_lines = false
menu_bar = true
agent_notes = false
transparent_background = false
  • theme = "auto"（または --theme auto）は起動時に端末背景を問い合わせ、明背景なら github-light-default、暗背景なら github-dark-default を選ぶ。
  • 旧 id（例: graphite、paper）は互換エイリアスとして残る。
  • exclude_untracked は Git / Sapling の作業ツリー hunk diff にのみ効く。
  • アプリ内で t、または View → Themes… でテーマセレクタを開く。
  • menu_bar = false でメニューバーを消し、キーボード中心のレビューで 1 行分の端末高さを確保できる（0.17）。

カスタムテーマ

theme = "custom"

[custom_theme]
base = "catppuccin-mocha"
label = "My Theme"
accent = "#7fd1ff"
panel = "#10161d"
noteBorder = "#c49bff"

[custom_theme.syntax]
keyword = "#8ed4ff"
string = "#c7b4ff"
comment = "#6e85a7"

カスタム色はすべて #rrggbb。組み込みテーマを base に継承し、必要な色だけ上書きする。

7 — Pager 連携と OpenTUI 埋め込み
Git / jj / Sapling pager 
# Git
git config --global core.pager "hunk pager"

# Jujutsu（jj config edit --user）
[ui]
pager = ["hunk", "pager"]
diff-formatter = ":git"

# Sapling（sl config -u）
[pager]
pager = hunk pager
未追跡ファイル: 自動取り込みは Hunk 自身の hunk diff 作業ツリーローダのみ。hunk pager 経由の git diff では Git がパッチ内容を決めるため、未追跡は出ない。
hunkdiff/opentui

HunkDiffView と下位プリミティブを hunkdiff/opentui から公開している。自前の OpenTUI アプリに同じ diff レンダラを埋め込める。peer は OpenTUI / React（例: @opentui/core@^0.4.2）。API と実行例は上流の docs/opentui-component.md。

8 — リポジトリ構成（処理の層）
ざっくりデータフロー

CLI（src/core/cli.ts ほか）が Git / jj / Sapling / ファイル入力を解釈し、セッションと broker（packages/session-broker*）を介して TUI（src/ui）へ差分とメタデータを流す。

flowchart TD A[CLI hunk / show / patch] --> B[src/core VCS・パス解決] B --> C[src/session プロトコル] C --> D[session-broker デーモン] D --> E[src/ui OpenTUI + Pierre] C --> E F[hunk session / skill] --> D
参照