herdr 完全ガイド：tmux の代わりに「エージェント対応」マルチプレクサを使う

前回の tmux 記事で、ペインごとに Claude Code を立てて分業させる話を書いた。実際にやると分かるが、tmux で複数の Claude Code を並走させるとどのペインが「入力待ち」で止まっているのか分からなくなる。別ウィンドウで作業している間に、裏のエージェントが Bash の実行許可を求めたまま10分待ちぼうけ——これが日常になる。この問題を正面から解決するのが herdr だ。この記事は tmux 記事の続編として、herdr 0.7.1（macOS）を実際に使って検証した内容をまとめる。機能の紹介記事は他にもあるので、ここでは実際に操作している画面（全GIF実録）と、やってみて詰まったところに比重を置く。

要点（先に結論）

• herdr とは：Rust製シングルバイナリの「エージェント・マルチプレクサ」。tmux と同じく分割・セッション保持・復帰ができ、さらに Claude Code などのAIエージェントの状態（作業中／入力待ち／完了）を理解する。
• 最大の差分：左サイドバーに全エージェントの状態が常時表示される。別の作業をしていても「赤（入力待ち）」が一目で分かる。終わったら通知も出る。
• 構造：セッション > ワークスペース > タブ > ペイン。tmux の「セッション > ウィンドウ > ペイン」に対し、セッションとタブの間に「ワークスペース」が1段挟まる。
• 操作感：prefix は tmux と同じ Ctrl-b。分割・detach・attach の感覚もほぼそのまま持ち込める。
• 設定：独自DSLではなく普通の TOML（~/.config/herdr/config.toml）。
• 自動化：ソケットAPI（CLIサブコマンド）で agent send → agent wait → agent read ができる。tmux の send-keys / capture-pane でやっていた工作が公式APIになっている。
• 正直な結論：エージェントを並走させないなら tmux で足りる。並走させるなら herdr に移る価値がある。

herdr で何ができるか / tmux と何が違うか

herdr は GitHub の ogulcancelik/herdr で開発されている（公式: herdr.dev）。GUIなし・Electronなし・アカウント不要・テレメトリなし、単一バイナリ約10MB。対応OSは Linux / macOS / Windows（ベータ）。

tmux でできたことは、だいたいそのままできる。違いは表で見るのが早い。

対応エージェントは claude, codex, copilot, devin, cursor, pi, droid, kimi, opencode, kilo など14以上。herdr integration install claude でネイティブ統合が入り、フック経由で状態が意味的に報告される（セッション復元も対応）。

インストール

# インストールスクリプト
curl -fsSL https://herdr.dev/install.sh | sh

# または Homebrew
brew install herdr

mise や Nix でも入る。更新は herdr update 一発。

起動は herdr。名前付きセッションで始めるなら：

herdr --session work   # "work" という名前のセッションを起動 or attach

herdr はサーバー/クライアント型で、サーバーは常駐する。状態は herdr status で確認できる。なお herdr の中で herdr を起動する nested 起動はデフォルト無効で、やると「nested herdr is disabled by default」というエラーになる。

4つの階層：セッション・ワークスペース・タブ・ペイン

tmux の3階層に対して、herdr は4階層。ここが最初の戸惑いどころなので押さえておく。

増えているのは「ワークスペース」の段だ。ポイントは、tmux で「案件ごとにセッションを分ける」とやっていた運用が、herdr では「1セッション内のワークスペース切替」になること。detach/attach は1回で済み、案件の行き来はワークスペース切替（後述）でやる。

厳密なことを言えば、tmux にも全セッションを束ねる「サーバー」が裏に居るので、階層の数はどちらも4つと数えられる。違いは役割の切り方で、herdr は「attach する単位（セッション）」の中に「案件の単位（ワークスペース）」を最初から持っている。tmux のサーバーは意識しない裏方だが、herdr のセッションは表に出てくる、という対応だ。

画面の見方：

• 左サイドバー：上段に「spaces」（ワークスペース一覧）、下段に「agents」（全ワークスペース横断のエージェント一覧と状態）。prefix b で開閉。
• 上部にタブバー：今のワークスペースのタブが並ぶ。

エージェント状態は4色で出る。

別ワークスペースで作業中でも、サイドバーで全エージェントの状態が見える。エージェントが終わったら通知（toast / サウンド、設定可）も出る。

セッション操作（detach / attach）

prefix は既定 Ctrl-b。tmux と同じなので、指はそのまま使える。detach だけ prefix d ではなく prefix q に変わる。detach すると「herdr: detached from server / Run herdr session attach demo to reattach」と表示され、戻り方まで教えてくれる。

herdr --remote user@server は、SSH越しにリモートの herdr サーバーへ手元のクライアントから接続する。ssh + tmux の組み合わせと違って、画像ペーストなどのローカル端末の機能が生きるのが利点。

ペイン操作（画面分割）

tmux の % / " という覚えにくい既定と違い、最初から v（vertical に切る＝右に分割）と -（下に分割）。移動は矢印ではなく vim 風の hjkl が既定。マウスも最初から完全対応なので、クリックでペイン選択・ドラッグもそのまま効く。

タブ操作（tmux のウィンドウ相当）

prefix c を押すとタブ名を聞くダイアログが出る（Enter で確定、Ctrl-c でクリア、esc でキャンセル）。tmux のように無名のウィンドウが量産されず、最初から名前をつける流れになっているのは地味に良い。

ワークスペース操作（herdr にしかない階層）

案件Aと案件Bを行き来するなら、prefix Shift+n で作って prefix Shift+w で改名（既存名が入った状態で出るので Ctrl-c でクリアして入力）、以後は prefix w のナビゲートモードで上下キー切替。tmux の prefix s によるセッション切替とほぼ同じ感覚で、detach を挟まない分だけ速い。ナビゲートモード中は hjkl でペイン移動もできる。

設定：config.toml

設定は ~/.config/herdr/config.toml。tmux の独自DSLと違い、普通の TOML で書ける。まず全デフォルト設定をコメント付きで出力して眺めるのがいい。

herdr --default-config   # 全デフォルト設定をコメント付きで出力

tmux 記事と同じく prefix を Ctrl-a に変える例：

[keys]
prefix = "ctrl+a"

テーマは内蔵から選ぶだけ。catppuccin（既定）, terminal, tokyo-night, dracula, nord, gruvbox, one-dark, solarized, kanagawa, rose-pine, vesper があり、OSのライト/ダーク自動追従もできる。通知は [ui.toast] の delivery = "off" | "herdr" | "terminal" | "system"、エージェント状態変化のサウンドは [ui.sound]。新しいペインのシェルや作業ディレクトリのポリシー（follow / home / 固定パス）は [terminal] で決められる。

反映は herdr server reload-config。キー設定を戻したくなったら herdr config reset-keys。

エージェント状態が見える（Claude Code 連携）

ここが herdr の本体。まず統合を入れる。

herdr integration install claude

これで ~/.claude/hooks/herdr-agent-state.sh が入り、Claude Code の状態がフック経由で意味的に報告されるようになる。ペインで claude を起動すると、サイドバーの agents 欄に「ワークスペース名 · タブ名 / 状態 · claude」という行が現れる。

実際の動き（検証済み）：

• Claude Code に作業を投げると working（黄） になる
• Bash 実行許可などの確認待ちになると blocked（赤） になる
• 待機に戻ると idle（緑）。裏のワークスペースでタスクが終わると done（青） が付く

別のワークスペースで作業していても、どのエージェントが待ちぼうけになっているかが一目で分かる。tmux 記事で書いた「ペインごとに Claude Code を分業させる」運用の一番の穴——「裏のペインが許可待ちで止まっているのに気づかない」——がこれで塞がる。終わったら toast やサウンドで通知も飛ばせるので、画面を見ていなくてもいい。

小ネタ：この記事を書いている Claude Code 自身も herdr の中で動いている。ペイン内に HERDR_PANE_ID などの環境変数が入っているので、エージェント側からも「自分が herdr の中にいる」と分かる。

ソケットAPI：tmux にない最大の差分

herdr の各ペインには HERDR_SOCKET_PATH, HERDR_PANE_ID, HERDR_WORKSPACE_ID, HERDR_TAB_ID, HERDR_ENV という環境変数が入っていて、CLI サブコマンドはこのソケット経由でサーバーを操作する。外部からでも HERDR_SOCKET_PATH を指定すれば任意のセッションを操作できる。

tmux の send-keys / capture-pane に相当する操作が一通りある。

herdr pane list                                   # ペイン一覧
herdr pane split --current --direction right      # 分割
herdr pane run <pane_id> "npm test"               # コマンド+Enter送信
herdr pane read <pane_id> --lines 50              # 出力読み取り
herdr pane send-keys <pane_id> enter              # キー送信
herdr wait output <pane_id> --match "PASS"        # 特定の出力が出るまで待つ

だが本命はエージェント系。ペイン番号ではなくエージェント名で指定でき、状態を理解した形で待てる。

herdr agent list                                        # 検出済みエージェントと状態
herdr agent send claude "この変更をレビューして"           # エージェントに指示（文字入力）
herdr pane send-keys <pane_id> enter                    # Enterで送信
herdr agent wait claude --status idle --timeout 60000   # idleになるまでブロックして待つ
herdr agent read claude --lines 30                      # 出力を読む

1つ注意：agent send は文字を入れるだけで、送信（Enter）はしない。Enter は pane send-keys で別に送る。tmux の send-keys で末尾に Enter を付けていたのと同じ流儀だ。

tmux 記事の応用編で「send-keys で別ペインの Claude Code に指示を飛ばす → capture-pane で読む」という工作をやったが、あれには「相手の完了を待てない」という弱点があった。herdr では agent send → agent wait --status idle → agent read の3コマンドで公式APIとして同じことができる。「実装役に投げる → 終わるまで待つ → 結果をレビュー役に渡す」がシェルスクリプトで素直に書ける。

ワークスペースやタブも CLI から作れる（herdr workspace create --cwd PATH、herdr tab create --label TEXT など）。さらに git worktree 統合もあり、herdr worktree サブコマンドや prefix Shift+g で新規 worktree を切れる。並行して複数エージェントに別ブランチを触らせる用途に向く。

実際にハマったところ

検証中に実際につまずいた点。ドキュメントを読むだけでは出てこない類の話だ。

• herdr の中で herdr は起動できない。うっかりやると error: nested herdr is disabled by default と怒られる。ご丁寧に "recursive descent denied. there is, in fact, such a thing as too much herdr."（再帰は却下。herdr の過剰摂取というものは実在する）という一文付き。SSH 先の herdr に入りたいなら herdr --remote を使う。
• リネーム系ダイアログは既存名が残った状態で開く。ワークスペース改名（prefix Shift+w）でそのまま打つと projectwebapp のように後ろに連結される。Ctrl-c で一度クリアしてから入力する。
• 新規タブのたびに名前を聞かれるのがテンポ悪いと感じたら、config で prompt_new_tab_name = false。生成名で即作成になる。
• 名前付きセッションを外から操作するには、ソケットを明示する。HERDR_SOCKET_PATH=~/.config/herdr/sessions/<名前>/herdr.sock herdr pane list のように指定すれば、attach していないセッションも CLI から触れる。

tmux から移行する人向け：対応表

prefix・ズーム・タブ切替あたりは同じキーなので、移行コストは見た目より小さい。体が覚え直すのは detach（d→q）と分割（%→v）くらい。

tmux のままでいい人 / herdr に移る価値がある人

正直に書く。

tmux のままでいい人：

• エージェントを並走させない。Claude Code は1つ、あるいは使っていない
• tpm・resurrect などのプラグイン資産に依存している
• 困ったとき検索で解決したい（情報量は tmux が圧倒的。herdr はまだ新しく、事例が少ない）
• 枯れたツールを長く使いたい

tmux 記事で書いた「detach で放置」「分割で並べて見る」だけの用途なら、tmux で何も困らない。

herdr に移る価値がある人：

• Claude Code を複数並走させていて、「どれが止まってるか」を目視巡回している
• send-keys / capture-pane でエージェント連携の工作をしたことがある（それ、公式APIになってる）
• 案件ごとに worktree を切ってエージェントに並行作業させたい
• tmux の設定DSLに疲れた

要するに分かれ目は「エージェントを何個回すか」。1個以下なら tmux、2個以上なら herdr、が今のところの結論。

まとめ：最悪これだけ覚えればいい

tmux 経験者なら、次の4つで今日から動ける。

• herdr --session 名前 … 始める
• prefix q で離れる → herdr session attach 名前 で戻る（tmux の d が q になっただけ）
• prefix v / prefix - … 右／下に分割、prefix h/j/k/l で移動
• herdr integration install claude … これでサイドバーにエージェントの状態が出る

もう少し慣れたら：

tmux の価値が「detach と分割」だったのに対し、herdr の価値は「エージェントの待ちぼうけが見える」に尽きる。複数の Claude Code を回し始めたら、思い出してほしい。