herdr に hunk プラグインを入れてエージェントの差分レビューを楽にする

注: 本記事は AI と協働で行った開発環境セットアップの備忘録です。

はじめに

普段、Claude Code や Codex などのコーディングエージェントを herdr というターミナルマルチプレクサ上で動かしています。herdr は複数エージェントの状態（作業中 / 入力待ち / 完了）を一覧できるのが便利です。

エージェントが書いた変更のレビューは、これまで VS Code など IDE 側から起動してエディタ標準の差分プレビューで見ていました。これはこれで特に不都合なく使えているのですが、herdr と差分ビューア hunk の組み合わせが話題になっていたので、試しに導入してみることにしました。

使うのはプラグイン edmundmiller/herdr-plugin-hunk です。hunk は「エージェントが書いた変更セットのレビュー」に特化したターミナル差分ビューアで、このプラグインと組み合わせるとキー一発で隣のペインに差分が開くようになります。

前提条件

herdr 0.7.0 以上（導入時は 0.7.4）
Python 3（プラグインのスクリプトが使用。macOS 標準の /usr/bin/python3 で足ります）
hunk CLI 本体（または bunx hunkdiff）

導入手順

1. hunk CLI をインストール

Homebrew に formula があるのでそれを使いました。

brew install hunk
hunk --version  # 0.17.2

Homebrew を使わない場合は npm の hunkdiff パッケージ（bunx hunkdiff）でも動きます。

2. プラグインをインストール

herdr にはプラグイン機構が組み込まれていて、GitHub リポジトリを指定するだけで導入できます。

herdr plugin install edmundmiller/herdr-plugin-hunk

インストール前にプレビュー（提供されるアクション一覧やコミットハッシュ）が表示され、確認後に hunk.diff という ID で登録されます。状態は次のコマンドで確認できます。

herdr plugin list
# - hunk.diff (Hunk Diff) enabled [github:edmundmiller/herdr-plugin-hunk@...]

herdr plugin action list  # 提供アクションの一覧（JSON）

3. キーバインドを設定

プラグインのアクションは ~/.config/herdr/config.toml の [[keys.command]] で type = "plugin_action" を指定してキーに割り当てられます。一番よく使う「ワークツリーの未コミット差分を split で開く」を prefix+d（Ctrl+B → d）に割り当てました。

[[keys.command]]
key = "prefix+d"
type = "plugin_action"
command = "hunk.diff.worktree-split"
description = "hunk worktree diff"

command は プラグインID.アクションID 形式のグローバル一意な識別子です。設定後はサーバ再起動なしで反映できます。

herdr server reload-config

なお、キーを選ぶときはデフォルトバインドとの衝突に注意してください。たとえば prefix+shift+d は close_workspace に割り当て済みなので避けました（d 単体は未使用でした）。

基本的な使い方

キー操作

herdr 内のペイン（対象リポジトリのディレクトリ）で Ctrl+B → d を押すと、隣に split ペインが開いてワークツリーの差分が hunk で表示されます。エージェントがターンを終えたタイミングで押せば、書かれた変更をそのままレビューできます。

提供アクション

アクションは「差分の種類 × 表示先」の 6 つです。

アクション	差分	表示先
`hunk.diff.worktree-split`	未コミットの変更	split ペイン
`hunk.diff.worktree-tab`	未コミットの変更	タブ
`hunk.diff.staged-split`	ステージ済みの変更	split ペイン
`hunk.diff.staged-tab`	ステージ済みの変更	タブ
`hunk.diff.branch-split`	ブランチ全体の差分	split ペイン
`hunk.diff.branch-tab`	ブランチ全体の差分	タブ

キーに割り当てていないアクションは CLI から直接呼べます。

herdr plugin action invoke hunk.diff.staged-split

テーマ

hunk の配色は環境変数 HUNK_THEME で指定できます（例: HUNK_THEME=catppuccin-mocha）。

補足: 類似プラグイン

hunk 連携のプラグインは他にもあります。

herdr-plugin-hunk-autodiff — エージェントが未コミット変更ありでターンを終えると自動で差分ペインを開く
herdr-hunk — fzf でコミット・範囲・stash を選んで表示。自動オープン機能も含む

今回はもっともシンプルな edmundmiller 版を選びました。「エージェントの完了に気づいたら自分でキーを押す」で十分回っていますが、自動オープンが欲しくなったら autodiff 版への乗り換えを検討しようと思います。

まとめ

brew install hunk + herdr plugin install edmundmiller/herdr-plugin-hunk の 2 コマンドで導入できます
[[keys.command]] の type = "plugin_action" でキーに割り当て、herdr server reload-config で即反映できます
prefix+d 一発でエージェントの書いた差分がレビューできるようになり、IDE に切り替えずターミナル内で完結する選択肢が増えました。普段の IDE の差分プレビューと使い分けながら、しばらく試してみようと思います