はじめに
AI コーディングエージェントを複数走らせるようになってから、「どのペインが承認待ちで止まっているのか」を探して端末をぐるぐる巡回するのが地味なストレスになっていた。そこで試したのが herdr だ。ひとことで言うと「AI エージェント版の tmux」で、Rust 製のシングルバイナリ。tmux 相当のペイン分割・セッション永続化に加えて、各ペインで動いているエージェントが blocked / working / done / idle のどれなのかをサイドバーで色分け表示してくれる。GUI の専用アプリと違って、いま使っている端末の中でそのまま動くのがいい。
結論から言うと、導入そのものは一瞬で終わったのに、**「2つ目のエージェントがサイドバーに出てこない」**という一点で盛大に回り道をした。原因は herdr でもエージェントでもなく、端末（iTerm2）の使い方だった。同じ構成で入れる人が同じ穴に落ちないように、たどった順番のまま残しておく。
この記事の環境は以下のとおり。
- macOS
- 端末: iTerm2
- herdr（執筆時点の最新は v0.7.1）
- 動かしたエージェント: Claude Code v2.1.183 / OpenAI Codex v0.144.1（model: gpt-5.5 xhigh）
先にまとめ
急ぐ人向けに、先に結論を3点。
- できたこと: herdr で Claude Code と codex を1画面に並べ、サイドバーで両方の状態を追える状態にできた。
- いちばんの罠: エージェントは必ず「herdr のペインの中」で起動する必要がある。端末（iTerm2）側の画面分割で開いたペインは herdr の管理外なので、そこで codex を動かしても永遠にサイドバーに出ない。
- 体感: トラブル自体は herdr の外（端末の使い方）に起因。仕組みを理解したら一本道だった。
そして、これが最短の正解手順。
# 1. インストール（Homebrew が楽）
brew install herdr
# 2. プロジェクトのディレクトリで起動
cd ~/project/weather-cli
herdr
# 3. ★ここが肝★ 分割は「herdr の中」で行う。
# プレフィックス Ctrl+B を押して指を離し、続けて v（縦分割）
# ↓ できた各ペインでエージェントを起動
claude # 左ペイン
codex # 右ペイン（herdr 管理下なのでサイドバーに出る）端末側の「Split Pane」で割ってはいけない、という一点さえ守れば、あとは素直に動く。以降は、それに気づくまでの実録。
導入：brew で入れて起動まで
インストールは Homebrew で一発だった。
brew install herdr公式ドキュメントによると curl -fsSL https://herdr.dev/install.sh | sh でも入るが、更新を brew に任せたかったので Homebrew を選んだ。
プロジェクトのディレクトリに移動して herdr と打つと、ワークスペースがひとつ自動で開く。画面は左に spaces（プロジェクト単位のまとまり）と agents（エージェント一覧）のサイドバー、中央がペインという構成。tmux で言う session / window / pane が、herdr では space / tab / pane に対応している。起動ディレクトリの Git リポジトリ名を拾って勝手に命名してくれるので、セッション名を付ける儀式は不要だった。
左ペインで claude（Claude Code）を起動すると、左下の agents に weather-cli / idle · claude と表示された。状態がちゃんと出ている。ここまでは気持ちよかった。
つまずき①：codex がエージェント一覧に出てこない
問題はここから。左の claude の隣に、もうひとつエージェントを並べたい。画面を右に分割して codex を起動した。codex 自体は問題なく起動し、OpenAI Codex (v0.144.1) のウェルカム画面が出た。
ところが、左下の agents 一覧には claude しか出てこない。codex がいない。
当たりをつけて試す（が、外す）
最初に疑ったのは「検知の対象になっていないのでは」だった。herdr はプロセス名と画面内容からエージェントを自動検知する。当時、端末のタイトルバーが node になっていたので、「codex が node プロセスとして見えていて、herdr が codex だと認識できていないのだろう」と考えた。
そこで、codex 用の公式インテグレーションを入れれば直るはずだと踏んで、インストールした。
herdr integration install codex入ったかどうかは status で確認できる。
❯ herdr integration status
...
claude: not installed (/Users/<user>/.claude/hooks/herdr-agent-state.sh)
codex: current (v6) (/Users/<user>/.codex/herdr-agent-state.sh)
copilot: not installed (/Users/<user>/.copilot/hooks/herdr-agent-state.sh)
...codex: current (v6) と出ている。インテグレーションはちゃんと入った。なのに agents 一覧には相変わらず codex が出ない。
次に「起動直後で状態が確定していないだけかも」と考え、codex に実際にタスク（コードレビュー）を投げてみた。codex は Working (11s) と表示され、git status や git diff を走らせ始めた。動いている。それでもサイドバーには出てこない。
ちなみにこのとき、codex の出力に次の警告が混ざっていた。
/Users/<user>/.zlogin:9: nice(5) failed: operation not permitted一瞬ドキッとしたが、これは herdr とは無関係だった。codex がコマンドをサンドボックスで実行する際、シェル起動ファイル（.zlogin）にある nice（プロセス優先度の変更）がサンドボックス内で許可されずに出る警告で、git コマンド自体は動いている。実害はない。
診断コマンドで手が止まる
行き詰まったので、herdr の診断コマンドを叩いてみた。
❯ herdr agent explain
usage: herdr agent explain <target> [--json]
usage: herdr agent explain --file PATH --agent LABEL [--json]対象（ターゲット）の指定が要る、という使い方エラー。ここで逆に気づいた。そもそも explain の対象にできる「herdr が管理しているペイン」に、codex が入っていないのでは？
真因：codex は herdr の「外」で動いていた
画面をよく見ると、構成がおかしかった。iTerm2 自体を左右に分割していて、
- 左ペイン …
zsh (herdr)= ここで herdr が動いている（中に Claude Code） - 右ペイン …
weather-cli (codex)= ここは iTerm2 が直接開いた素のペインで、そこに codex がいる
つまり、右の codex は「iTerm2 の画面分割」で開いた別ペインで、herdr の管理下にまったく入っていなかった。herdr は「自分のペインの中で動いているプロセス」を検知してサイドバーに出す仕組みなので、herdr の外で動いている codex は、インテグレーションを入れようがタスクを投げようが、検知しようがない。
公式ドキュメントを読み直すと、検知は「プロセス名マッチング＋画面内容のヒューリスティック」で、herdr が管理するペインが前提になっている。加えて、Claude Code や Codex のインテグレーションは主にネイティブのセッション復元（サーバー再起動後に会話を復元する）のためのもので、状態表示そのものは画面解析ベースとされている。つまり、①でインテグレーションを入れたのは、この問題に対しては完全に的外れだった（セッション復元のためには無駄ではないが）。
これで、何をやっても codex が出なかった説明が全部ついた。「分割は herdr の中でやる」——これが答えだった。
つまずき②：herdr 内で分割できない（右クリックとプレフィックス）
じゃあ herdr の中で分割しよう、と右ペインを閉じて、herdr のペイン上で右クリックした。ところが出てきたのは iTerm2 のコンテキストメニュー（New Window / Split Pane Vertically / …）で、herdr のメニューではなかった。ここから分割すると、また iTerm2 側の分割になってしまう。
調べると、これは iTerm2 の仕様だった。iTerm2 はセッション内で右クリックすると必ず自分のコンテキストメニューを開くので、右クリックが herdr まで届かない。iTerm2 のドキュメントによれば、右ボタンだけをアプリに転送する簡単な設定はなく、転送設定があるのは Ctrl+クリックのみ（Preferences → Pointer の「^-Click reported to apps」）。
「じゃあキーボードで」と思ったが、これも最初は「効かない」と感じた。結論を言うと、効かないのではなく、押し方を間違えていた。herdr のプレフィックスは tmux と同じ Ctrl+B だが、これは同時押しの一発ショートカットではなく 2ステップだ。
Ctrl+Bを押して、一度指を離す- 続けて操作キーを単独で押す（縦分割なら
v）
Ctrl+B を押した瞬間は画面に何も起きないので「反応がない」と勘違いしていたが、実際は次のキー入力を待っている状態だった。「Ctrl+B → 離す → v」で、herdr の中でスパッと縦分割できた。
できた新しいペインで codex を起動したら、ついに agents 一覧に codex が並んだ。長かった。
マウス操作にこだわるなら、iTerm2 のプロファイル設定（Profiles → Terminal）でマウスレポートを有効にすれば左クリックのフォーカスやドラッグは herdr に伝わる。ただし右クリックメニューまで欲しいなら、自前の右クリックメニューを持たない端末（Alacritty や Ghostty など）に乗り換えるのが確実だ。iTerm2 のまま使うなら、素直にキーボードのプレフィックスを使うのが一番速い。
設定をカスタマイズする（config.toml）
一通り動いたので、~/.config/herdr/config.toml を実用寄りに調整した。最終的にこうした（キー名は公式リファレンス準拠）。
# ── 基本 ──
onboarding = false
# ── テーマ ──
[theme]
name = "catppuccin"
auto_switch = true # macOS のライト/ダーク切替に追従
light_name = "catppuccin-latte"
dark_name = "catppuccin"
# ── サイドバー / エージェント一覧 ──
[ui]
agent_panel_sort = "priority" # 対応が要る順（blocked→done→working→idle）に並ぶ
# ── 通知（エージェントが完了 or 入力待ちになったら macOS 通知）──
[ui.toast]
delivery = "system"
delay_seconds = 1
# ── 日本語入力まわり（Mac 向け）──
[experimental]
switch_ascii_input_source_in_prefix = true # プレフィックス操作中だけ ASCII 入力に自動切替
reveal_hidden_cursor_for_cjk_ime = true # Claude Code/codex 上でも IME 変換窓が正しい位置に出る
cjk_ime_agents = ["claude", "codex"]いちばん効いたのは agent_panel_sort = "priority"。デフォルトのスペース順（"spaces"）だと固定表示だが、priority にすると入力待ちや完了のエージェントが自動で一覧の上に来るので、「今どれを見るべきか」が上から順に分かる。herdr の旨味が一番出る設定だと思う。
Mac で日本語を使う人には下2つの [experimental] が地味に効く。switch_ascii_input_source_in_prefix は、日本語 IME をオンにしたまま Ctrl+B を押しても、プレフィックス操作の間だけ ASCII 入力に自動で切り替わる。つまずき②の「かな入力中だとショートカットが効かない」系の事故を防げる。reveal_hidden_cursor_for_cjk_ime は、自前でカーソルを描く TUI（Claude Code や codex）で日本語の変換候補ウィンドウが変な位置に出る現象を直すものだ。
反映は再起動不要で、次のコマンドでいける。
herdr server reload-configUI 系はこれで即反映される。もし一部が効かない場合は起動時のみ反映される設定なので、そのときだけ herdr server stop で一度落として再起動する。キーバインド一覧は Ctrl+B → ? でいつでも確認できる。
ハマりどころまとめ
| 症状 | 原因 | 対処 |
|---|---|---|
| 2つ目のエージェント（codex）が agents に出ない | 端末（iTerm2）の分割で開いたペインは herdr の管理外。そこで起動しても検知されない | 分割は herdr の中で行い、そのペインでエージェントを起動する |
| インテグレーションを入れても出ない | codex のインテグレーションは主にセッション復元用。状態表示は画面解析ベースで、そもそも herdr 管理下でないと動かない | 真因は上記。インテグレーションは復元目的として別途入れておけばよい |
| 右クリックで herdr のメニューが出ない | iTerm2 が右クリックを自分のメニューに固定している仕様 | キーボードのプレフィックスを使う。マウス重視なら Ghostty / Alacritty へ |
| キーボードショートカットが効かない | プレフィックスは 2 ステップ（Ctrl+B を離してから操作キー） | Ctrl+B → 離す → v の順で押す |
.zlogin nice(5) failed: operation not permitted | codex のサンドボックス実行で nice が拒否されているだけ | 実害なし。放置で可 |
これから試す：エージェントに herdr を操作させる（※未検証）
ここは導入の続きとして「これから試す」枠。まだ実際には回していないので、公式情報ベースのメモとして残す。
herdr には CLI とローカルの Unix ソケット API があり、エージェント自身がペインを作ってコマンドを走らせ、完了を待って結果を回収できる。公式には「agent skill」という Markdown の指示ファイルが用意されていて、これをエージェントに読み込ませると、HERDR_ENV=1（herdr のペイン内で動いているとき）に herdr の CLI を使うようになる。導入は次の一発とされている。
npx skills add ogulcancelik/herdr --skill herdr -gこれができると、たとえば「Claude Code に実装させ、右に新ペインを開いて codex にレビューさせ、完了を待って結果を回収し、指摘を反映して修正し、最後に PR を出す」といった一連を、フォーカスを移さずに回せる——という触れ込み。内部的には herdr pane split --no-focus / pane run / wait agent-status --status done / pane read あたりが使われるらしい。
実際に回すときの注意として、承認待ち（blocked）で wait がハマる点と、PR 作成のような取り消しにくい公開アクションの直前は人間のチェックポイントを挟むべき点は意識しておきたい。ここは次回、実際に試して別記事にする予定。
やってみての所感
herdr 自体は素直で良いツールだった。今回ハマった原因は全部 herdr の外——「端末の分割で開いたペインは herdr の管理外」という一点の理解不足に集約される。逆に言うと、エージェントは必ず herdr のペインの中で起動するという原則さえ最初に知っていれば、導入は本当に一瞬で終わる。
向いているのは、Claude Code や codex を複数同時に走らせていて「どれが承認待ちか」を常に気にしている人。単一エージェント運用で tmux のセッション永続化で足りているなら、無理に乗り換える必要はないと思う。
次は agent skill でのオーケストレーションを実際に回してみて、承認待ちのハンドリングや PR までの流れがどこまで実用になるかを見てみたい。
まとめ
- herdr の導入自体は
brew install herdr→herdrで一瞬。 - 最大の罠は「エージェントは herdr のペインの中で起動する」。端末側の分割で開くと永遠にサイドバーに出ない。
- iTerm2 では右クリックが奪われるので、分割はキーボードのプレフィックス（
Ctrl+Bを離してから操作キー）で。 agent_panel_sort = "priority"と[experimental]の日本語入力設定は入れておくと快適。
同じ端末構成で入れる人の回り道が、少しでも短くなればと思う。