エージェント

Next docs describe unreleased work from master. Stable docs remain at /docs/.

Herdr は複数のコーディングエージェントを同時に動かすために作られています。各エージェントは、シェル、ログ、プロンプト、実行中プロセスをそのまま保った実際のターミナルペインの中にいます。Herdr はどのペインにエージェントがいるかを追跡し、その状態をタブとワークスペースに集約し、すべてのターミナルを手作業で見回る代わりに、注意が必要なペインへ直接ジャンプできるようにします。

スクリプトや別のエージェントから連携させる方法は、エージェント自動化 を参照してください。

対応エージェント

一般的なコーディングエージェントは、追加設定なしで自動検出されます。重要な違いは Herdr がエージェントを見えるかどうかではありません。どのシグナルが idle、working、blocked を決定する権限を持つかです。

エージェント	状態の権威	インテグレーションの役割
Pi	インストール時はライフサイクルフック。それ以外はスクリーンマニフェスト	状態とセッション
OMP	インストール時はライフサイクルフック	状態
GitHub Copilot CLI	スクリーンマニフェスト	セッション
Devin CLI	スクリーンマニフェスト	セッション
Kimi Code CLI	インストール時はライフサイクルフック。それ以外はスクリーンマニフェスト	状態とセッション
Hermes Agent	インストール時はライフサイクルフック。それ以外はスクリーンマニフェスト	状態とセッション
Qoder CLI	スクリーンマニフェスト	セッション
Droid	スクリーンマニフェスト	セッション
OpenCode	インストール時はライフサイクルプラグイン。それ以外はスクリーンマニフェスト	状態とセッション
Kilo Code CLI	インストール時はライフサイクルプラグイン。それ以外はスクリーンマニフェスト	状態とセッション
MastraCode	インストール時はライフサイクルフック	状態とセッション
Claude Code	スクリーンマニフェスト	セッション
Codex	スクリーンマニフェスト	セッション
Cursor Agent CLI	スクリーンマニフェスト	セッション
Amp	スクリーンマニフェスト	なし
Grok CLI	スクリーンマニフェスト	なし
Antigravity CLI	スクリーンマニフェスト	なし
Kiro CLI	スクリーンマニフェスト	なし
Maki	スクリーンマニフェスト	なし

検出されるもののテストが薄いもの: Gemini CLI と Cline。未対応のエージェントも通常のターミナルプロセスとして問題なく動きます。ただし、インテグレーションを追加するかソケット API で状態を報告しない限り、詳細な状態は得られない可能性があります。

状態の権威

Herdr はまず各ペインのフォアグラウンドプロセスを検出します。その後、各ペインはひとつの状態権威を持ちます。

完全なライフサイクルフックを持つエージェントでは、インテグレーションがインストールされ、実行中のペインについて能動的に報告している間は、インテグレーションが権威です。Herdr はそのフック報告を idle、working、blocked とセッション識別に使います。同じライフサイクル権威に対してスクリーンマニフェストのフォールバックを並走させることはしません。これにより、真実の情報源が 2 つ競合する状況を避けます。

完全なライフサイクルフックを持たないエージェントでは、Herdr はフォアグラウンドプロセスを識別し、ライブの下部バッファのスクリーンスナップショットを読みます。そのスナップショットに対して TOML マニフェストを評価し、idle、working、blocked を分類します。それらを発するエージェントでは、マニフェストはターミナルタイトルと進捗 (OSC) シーケンスも検出の証拠としてマッチできます。その証拠がない場合は、スクリーンルールが単独で検出を担います。

スクリーンスナップショットは、スクロールされたビューポートではなく、ペインバッファの直近の下部から取得されます。Herdr でスクロールバックしても、検出は下部のライブなエージェント UI を追い続けます。

Claude Code、Codex、GitHub Copilot CLI、Droid、Qoder CLI、Cursor Agent CLI のインテグレーションは、意図的にライフサイクル権威にしていません。これらは復元のためのネイティブセッション識別を提供しますが、フックがライフサイクル全体をカバーしていません。許可承認の結果、Esc による中断、その他の遷移を見逃すことがあります。これらのエージェントでは、Herdr は引き続きスクリーンマニフェスト検出を使います。

VM とサンドボックスラッパー

Linux と macOS では、ホストから見えるラッパーが実際のエージェントプロセスを Herdr から隠すことがあります。ラッパーのコマンドに HERDR_AGENT=<agent> を設定して、どの既存エージェントのスクリーンマニフェストを使うべきか Herdr に伝えてください。たとえば、Linux では HERDR_AGENT=claude fence -- claude、macOS では HERDR_AGENT=claude nono run --profile claude-code -- claude を実行します。このヒントはそのフォアグラウンドプロセスにスコープされます。VM やコンテナの内部だけで設定しても Herdr からは見えません。また、継承されるすべてのフォアグラウンドプロセスをそのエージェントとして扱いたいのでない限り、グローバルな export は避けてください。

blocked 状態

スクリーンマニフェスト方式のエージェントでは、blocked の検出は意図的に厳格です。Herdr が blocked と判定するのは、ライブの下部バッファスナップショットが既知の承認・質問・許可 UI にマッチしたときだけです。既知のエージェントでどのマニフェストルールにもマッチしない場合、Herdr は idle にフォールバックし、explain の出力ではそのフォールバックに default_known_agent_idle_fallback というラベルを付けます。

つまり、見慣れない新しいエージェントプロンプトは、Herdr がその画面の形を学習するまで、最初は blocked ではなく idle と表示されることがあります。こうしたやり取りによって Herdr が入力を送ったり破壊的な操作をしたりすることはありません。影響するのは表示上の状態と wait だけです。

検出マニフェスト

バンドルされたマニフェストは Herdr の内部にあります。Herdr は herdr.dev でリモートマニフェストの更新も確認し、有効なエージェント別ルール更新を Herdr の再起動なしで自動適用します。リモートマニフェストは Herdr の state ディレクトリに保存されます。バックグラウンドのリモートマニフェスト確認を無効にするには [update] manifest_check = false を設定します。

ローカルオーバーライドは、プラットフォームの設定ディレクトリからリモートまたはバンドルのマニフェストを置き換えられます:

~/.config/herdr/agent-detection/<agent>.toml

ローカルオーバーライドが常に優先されます。ローカルオーバーライドがない場合、Herdr はキャッシュされたリモートマニフェストと実行中バイナリにバンドルされたマニフェストのうち、新しくて互換性のある方を使います。デバッグビルドでは、同じ設定ヘルパーが herdr-dev のような開発用ディレクトリを使うことがあります。無効なオーバーライドファイルは警告付きで無視され、Herdr はそのエージェントについてキャッシュされたリモートまたはバンドルのマニフェストにフォールバックします。

リモートマニフェストは、Herdr がすでに識別方法を知っているエージェントの検出ルールにパッチを当てるものです。完全に新しいエージェントの追加には、プロセス検出、ラベル、インテグレーション挙動のために Herdr バイナリのアップデートが引き続き必要です。

実行中のサーバーは起動時にアクティブなマニフェストをメモリに読み込みます。リモートマニフェストの自動更新は、新しいルールが書き込まれた後にそのメモリ内キャッシュをリロードします。herdr server update-agent-manifests を実行すると、リモートマニフェストの更新を即座に取得して実行中のサーバーをリロードします。ローカルオーバーライドを手で編集した後は、Herdr を再起動するか herdr server reload-agent-manifests を実行して、実行中のサーバーにファイルを適用してください。

ペインの状態表示がおかしいときは herdr agent explain を使ってください:

herdr agent explain <target>
herdr agent explain --file screen.txt --agent codex --json

ライブの explain は実行中のサーバーが評価するので、アクティブなマニフェストキャッシュを反映します。explain の出力には次が表示されます: エージェント、最終状態、完全なライフサイクル権威によってスクリーン検出がスキップされたかどうか、マニフェストのソースとバージョン、キャッシュされたリモートバージョン、ローカルオーバーライドによるシャドーイング、リモート更新の状況、マッチしたルール、可視の証拠フラグ、評価されたルールのマッチャーとリージョンの証拠、トランスクリプトビューアーでの更新スキップ理由、そしてどのルールにもマッチしなかったときの idle フォールバック理由です。

Herdr は外側のターミナル環境として tmux の中で動かせます。エージェント検出は、Herdr のペイン内で起動された tmux セッションの中までは調べません。シェルフレームワークが Herdr 内で自動的に tmux に入る場合、Herdr はペインのプロセスとして背後のエージェントではなく tmux を見ることになります。

状態のロールアップ

サイドバーは状態を上位へ集約します。

blocked なエージェントは、そのペイン、タブ、ワークスペースを blocked に見せます。working なエージェントはワークスペースをアクティブに見せます。done なエージェントは、あなたが確認するまで表示され続けます。

これが Herdr の中心的なワークフローです: 複数のエージェントを起動し、並行して働かせ、サイドバーでどのプロジェクトが判断を必要としているか、どれがまだ実行中か、どれがレビュー待ちかを把握します。

ダイレクトインテグレーション

使っている各エージェントのインテグレーションをインストールしてください。スクリーン検出だけに頼らず、フックやプラグインの報告を Herdr に提供します:

herdr integration install claude
herdr integration status

対応エージェントごとに、インテグレーションの名前と挙動は異なります。エージェント別の詳細と完全なインストール一覧はインテグレーションを参照してください。

カスタムエージェントラベル

表示用にエージェントターゲットの名前を変えられます:

herdr agent rename w1:p1 reviewer
herdr agent rename reviewer --clear

ターゲットには一意なライブエージェント名、または現在そのエージェントをホストしているペイン ID を使います。ターミナル ID とエージェント kind のラベルだけでは指定できません。

カスタムステータスラベル

インテグレーションは、ライフサイクル状態を意味的な状態としてのみ報告します。表示のカスタマイズは、ペインメタデータのトークンとして別に追加します。

herdr pane report-agent w1:p1 \
  --source custom:indexer \
  --agent docs-bot \
  --state working

herdr pane report-metadata w1:p1 \
  --source custom:indexer-display \
  --token summary=indexing

state は wait、通知、ロールアップを制御します。summary トークンは表示専用で、エージェントサイドバー行では $summary として使えます。

エージェントサイドバー行では、terminal_title または terminal_title_stripped も任意で使えます。どちらもデフォルト行には含まれません。前者は安全性のために正規化された最新の OSC 0/2 ターミナルタイトルを表示し、後者は先頭にある認識済みのアクティビティまたはスピナーのグリフ 1 つと、それに続く空白を除去します。これらの値は Herdr サーバーが所有し、コールドリスタートをまたいで保持されません。また、メタデータのタイトルや意味的なエージェント状態から独立しています。そのため、除去後のテキストが同じなら、スピナーのアニメーションで生のタイトルが変わってもペイン更新は発行されません。

エージェントに直接アタッチする

完全な Herdr UI ではなく、ひとつのエージェントターミナルに現在のターミナルをアタッチします:

herdr agent attach reviewer

ctrl+b q でデタッチします。リテラルの ctrl+b は ctrl+b ctrl+b で送ります。

マウスホイールまたは通常の page up/page down でスクロールします。通常の入力をすると最下部に戻ります。

別のダイレクトアタッチクライアントがすでに入力を所有している場合は --takeover を使います:

herdr agent attach reviewer --takeover

エージェントではないターミナルで同じダイレクトアタッチ挙動が欲しいときは herdr terminal attach <terminal_id> を使ってください。