ターミナルマルチプレクサを tmux から herdr に移行した

はじめに

ターミナルマルチプレクサを tmux から herdr へ移行しました。

herdr とは、AI コーディングエージェントの実行に特化したターミナルマルチプレクサです。tmux と同じくペイン・タブ・セッションを永続化しつつ、各ペインで動くエージェントの状態（idle / working / blocked / done）をサイドバーへネイティブに表示します。実装は Rust と TUI ライブラリの Ratatui です。公式は「one terminal for the whole herd」を掲げ、Electron 非依存・アカウント不要・テレメトリなしをうたっています。

本記事では、tmux と tmux-agent-sidebar プラグインで組んでいた環境を herdr へ置き換えた手順を紹介します。実際に自分の dotfiles へ導入した記録です。

なお、herdr は本記事の執筆時点でバージョン 0.7.1 です。今後のアップデートで挙動や設定が変わる可能性があります。最新の情報は公式ドキュメントを確認してください。

移行前の構成

移行前は tmux をマルチプレクサとして使い、エージェントの状態表示には hiroppy/tmux-agent-sidebar を利用していました。

このプラグインは、エージェントのフックからスクリプトを呼び出し、tmux のサイドバーに状態を描画します。私の環境では Codex と連携し、~/.codex/hooks.json から hook.sh を呼ぶ設定を入れていました。

tmux 側は次のような構成でした。

• プラグイン管理: tpm（Tmux Plugin Manager）
• テーマ: catppuccin（mocha）
• ステータスバー: battery / cpu / online-status / prefix-highlight
• セッション永続化: continuum / resurrect

なぜ移行するのか

移行の動機は、エージェントの状態表示をより自然な形で扱いたかったことです。

tmux-agent-sidebar は、tmux という「エージェント登場以前に設計されたツール」へ後付けでエージェント認識を足す仕組みです。一方 herdr は、エージェントの状態表示を最初から中核に据えています。ペインで動くプロセスをエージェントとして識別し、その状態を色付きのインジケーターでサイドバーへ表示します。

加えて、herdr にはマウスネイティブの操作や、SSH 経由でのリモートアタッチといった機能もあります。tmux の資産を活かしつつ、エージェント運用に寄せた選択肢として試す価値があると判断しました。

マルチプレクサの乗り換え先としては、以前 Zellij も試しました。ただ、私の使い方には合わず、当時は採用を見送りました。

一番の理由は、tmux で使っていた C-q プレフィックスをそのまま持ち込めなかったことです。Zellij は tmux のような単一プレフィックス方式ではなく、モーダルなキーバインド方式を採ります。既定では Primary Modifier（Ctrl）でモードへ入り、Secondary Modifier（Alt）でよく使う操作を実行します（Zellij ドキュメント）。

キーバインドや修飾キー自体は config.kdl でカスタマイズできます。ただし「単一のプレフィックスへ寄せる」という tmux 的な設計とは根本的に異なります。

その点、herdr は tmux と同じ単一プレフィックス方式を採ります。prefix = "ctrl+q" の 1 行で C-q をそのまま再現できました。この移行のしやすさも、herdr を選んだ理由の 1 つです。

インストール

herdr は Homebrew の core formula に登録されています。私は dotfiles を Homebrew で管理しているため、brew で導入しました。

$ brew install herdr

インストール後、バージョンを確認します。

$ herdr --version
herdr 0.7.1

dotfiles の .Brewfile からは tmux の行を削除し、代わりに herdr を追加しました。

brew "herdr"

設定

herdr の設定ファイルは ~/.config/herdr/config.toml です。次のコマンドで既定の設定を出力できます。

$ herdr --default-config

出力を見ると、[keys] のペイン移動は既定で prefix+h / prefix+j / prefix+k / prefix+l に割り当てられていました。私が tmux で使っていた Vim 風のキーバインドと一致していたため、この部分はそのまま活かせました。

旧 .tmux.conf の主要な設定を、次のように移植しました。

分割の方向は herdr の CLI で確認しました。herdr pane split --direction right は新しいペインを右に並べ（左右分割）、--direction down は下に並べます（上下分割）。旧 |（左右）と -（上下）の対応を保つため、split_vertical を | 相当、split_horizontal を - 相当としています。

lazygit の起動キーには注意が必要でした。tmux では prefix + g を使っていましたが、herdr では prefix+g が既定でワークスペース移動（goto）へ割り当て済みです。衝突を避けるため、herdr 公式の例にならって prefix+alt+g へ割り当てました。

最終的な config.toml は次のとおりです。既定値のままの項目は省略しています。

[theme]
name = "catppuccin"

[terminal]
default_shell = "/bin/zsh"

[keys]
prefix = "ctrl+q"

[[keys.command]]
key = "prefix+alt+g"
type = "pane"
command = "lazygit"

[ui]
mouse_capture = true

設定の反映は、サーバーを再起動せずに次のコマンドで行えます。

$ herdr server reload-config
{"id":"cli:server:reload-config","result":{"diagnostics":[],"status":"applied","type":"config_reload"}}

diagnostics が空で status が applied になっていれば、設定のパースに成功しています。

Claude Code 連携

herdr は主要なエージェントとの連携を組み込みで持ちます。連携の導入は herdr integration install <agent> で行います。

今回は Claude Code と連携させました。

$ herdr integration install claude
installed claude integration hook to /Users/<user>/.claude/hooks/herdr-agent-state.sh
ensured claude settings at /Users/<user>/.claude/settings.json

このコマンドは 2 つの変更を加えます。1 つは ~/.claude/hooks/herdr-agent-state.sh というフックスクリプトの生成です。もう 1 つは ~/.claude/settings.json への SessionStart フックの追記です。

追記されたフックは次の形です。

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "command": "bash '/Users/<user>/.claude/hooks/herdr-agent-state.sh' session",
            "timeout": 10,
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ]
  }
}

連携の状態は herdr integration status で確認できます。

$ herdr integration status
claude: current (v7) (/Users/<user>/.claude/hooks/herdr-agent-state.sh)

current と表示されれば、フックは最新の状態です。herdr のペイン内で Claude Code を起動すると、フックがセッション情報を herdr へ通知し、サイドバーの状態表示に反映されます。

ここで dotfiles 管理者向けの注意点があります。生成される settings.json のフックには、/Users/<user>/.claude/hooks/... という絶対パスが書き込まれます。複数マシンで dotfiles を共有している場合、パスがマシン名を含む点に気をつけてください。私はフックスクリプトを dotfiles 管理下へ置き、settings.json はセットアップ時に各マシンで herdr integration install claude を実行して整合させる運用にしました。

さらに herdr は、エージェント自身に herdr を操作させる仕組みも用意しています。公式リポジトリの SKILL.md をエージェントへ読み込ませると、ワークスペース・タブ・ペインの生成や、別ペインでのコマンド実行と結果回収といった調整を、エージェントが CLI・Unix ソケット API 経由で自律的に行えるようになります（この使い方は Zenn の記事が詳しいです）。私はこの SKILL.md を Claude Code のユーザースキルとして ~/.claude/skills/herdr/SKILL.md（実体は dotfiles 管理下）へ置きました。フックや settings.json と同じく ~/.claude は dotfiles で一括管理しているため、herdr 関連の設定をひとまとめに扱えます。herdr の SKILL.md は name と description を持つ frontmatter を最初から備えているため、~/.claude/skills/herdr/ へ置くだけで Claude Code のスキルとして認識されます。

tmux からの撤去

herdr が動くことを確認したうえで、tmux 関連の設定を撤去しました。

• .tmux.conf を削除
• .Brewfile から tmux を削除し、tmux 本体をアンインストール
• tmux-agent-sidebar を呼んでいた Codex のフック設定（~/.codex/hooks.json と config.toml のマーケットプレイス登録）を削除
• ~/.tmux/plugins（tpm と各プラグイン）を削除

ターミナルの自動起動も忘れずに書き換えます。私は Alacritty から tmux を自動アタッチしていました。

# 変更前
args = ["-l", "-c", "tmux a -t default || tmux new -s default"]

# 変更後
args = ["-l", "-c", "herdr"]

herdr はコマンド単体で、既存の永続セッションへのアタッチ、またはセッションの新規作成を行います。tmux の attach || new に相当する挙動を 1 コマンドで担ってくれます。

このほか、ghq で移動したときに tmux のセッション名をリポジトリ名へ変更する zsh のフックも持っていました。herdr はワークスペースを作業ディレクトリから自動でラベル付けするため、このフックは不要になりました。

移行して感じたこと

移行して得たものと、失ったものを整理します。

得たものは次の 3 点です。

• エージェント状態のネイティブな可視化。プラグインの後付けではなく、herdr 本体がサイドバーへ状態を表示します。
• マウス操作。ペインやタブをクリックやドラッグで扱えます。
• リモートアタッチ。herdr --remote <ssh-target> で、別マシンのセッションへアタッチできます。

一方で失ったものもあります。tmux のステータスバーへ表示していた battery / cpu / online-status などのウィジェットは、herdr には相当する機能がありません。これらの情報が必要な場合は、別の手段を検討する必要があります。

セッションの永続化については、continuum / resurrect による起動時の自動復元から、herdr の常駐サーバーによる永続化へ考え方が変わりました。herdr はサーバーが動き続ける限りエンジンとペインを保持し、クライアントをデタッチしてもエージェントは動き続けます。

おわりに

tmux から herdr への移行を紹介しました。

herdr は tmux の永続化やペイン操作という資産を引き継ぎつつ、エージェントの状態表示を中核に据えたマルチプレクサです。エージェントを日常的に複数動かす開発スタイルであれば、試す価値があると感じました。

一方で、herdr はまだ若いツールです。tmux の豊富なプラグイン資産や細かなカスタマイズを重視する場合は、現時点では tmux に分があります。自分の使い方に合うかどうかを見極めたうえで採用を判断してください。

参考資料

• herdr 公式サイト
• herdr ドキュメント
• ogulcancelik/herdr（GitHub）