herdr

Herdr

Herdr はターミナルをワークスペース、タブ、ペインに整理し、ペイン内で実行中のコーディングエージェントを認識して、現在のセッションを herdr CLI から利用できるようにします。

制御コマンドを実行する前に、このエージェントが Herdr 管理下のペイン内で実行されていることを確認してください。

test "${HERDR_ENV:-}" = 1

確認に失敗した場合は、Herdr 内で実行されていないことを伝え、そこで停止してください。Herdr の外部から、フォーカスされている Herdr セッションを調査または制御しないでください。

確認に成功した場合、PATH 内の herdr バイナリが現在のセッションと通信します。これを使って、隣接する作業を調査し、ターミナルのレイアウトを作成し、エージェントやコマンドを起動し、出力を読み取り、状態の変化を待機してください。

現在の CLI を把握する

インストール済みのバイナリがコマンド構文の基準です。まず、次を実行してください。

herdr --help

次に、サブコマンドを指定せずにコマンドグループを実行し、関連するコマンドグループを表示してください。

herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr session
herdr machine

確認のために herdr を引数なしで実行しないでください。TUI が起動またはアタッチされます。引数を省略して、状態を変更するネストされたコマンドを試さないでください。herdr workspace create のようなコマンドはデフォルト値で有効なため、実行されます。

ほとんどの制御コマンドは JSON を返します。識別子や状態を予測するのではなく、返された応答から読み取ってください。

レイアウト、ペイン、エージェントを理解する

作業に合った基本要素を選択してください。

• ワークスペース、タブ、ペインの構成で、ターミナルの場所を整理します。
• ペインコマンドは、通常のターミナル、シェル、テスト、サーバー、入力、出力を制御します。
• エージェントコマンドは、現在ペインを占有している、認識済みのコーディングエージェントを制御します。

ペインは、エージェントが含まれているかどうかにかかわらず存在します。agent start には、既存の使用可能なシェルペインが必要です。レイアウトの作成、分割、移動は行いません。通常のプロセスにはペインコマンドを使用してください。Herdr にエージェントの識別を検証させる場合や、idle、working、blocked、done、unknown のライフサイクル状態を解釈させる場合は、エージェントコマンドを使用してください。

エージェントコマンドでは、一意のアクティブなエージェント名、またはそのエージェントを現在ホストしているペイン ID のいずれかを指定できます。ターミナル ID やエージェントの種類だけを示すラベルは指定できません。名前は [a-z][a-z0-9_-]{0,31} に一致し、アクティブなエージェント間で一意である必要があります。名前は現在のペインの占有者に紐付けられ、そのエージェントが終了、解放、または置き換えられると解除されます。エージェントを Ctrl+Z で一時停止して、エージェント以外のコマンドを実行した場合、同じプロセスが存続している間は、その識別情報が保持されます。ただし、別の認識済みエージェントが引き継いだ場合、元の識別情報は保持されません。識別情報が保持されていても、そのエージェントがフォアグラウンドにいるとは限りません。入力を送信する前に、ペインを確認してください。

通常、idle と done はエージェントが入力を受け付けられる状態であることを示しますが、どちらも、未知の承認ダイアログが認識されていることや、識別情報が保持されたエージェントがフォアグラウンドにいることを保証しません。CLI/API はサーバーの既知状態を使って両者を区別します。明示的なフォーカスコマンドは対象を既知状態にしますが、読み取り操作ではそうなりません。各 TUI クライアントは完了済みの項目を個別に追跡するため、その Done バッジは CLI や別のクライアントのバッジと異なる場合があります。Antigravity と Grok は、バックグラウンドタスクやサブエージェントの実行中でも idle になることがあるため、安定状態になるのを待っても、これらのジョブが完了した証拠にはなりません。blocked は、Herdr が承認または質問の UI を認識したことを意味します。unknown はエージェントが存在するものの、Herdr が確信を持って分類できないことを意味します。完了した証拠ではありません。

ID と呼び出し元コンテキストの使用

公開 ID は不透明で安定したハンドルです：

• ワークスペース: w1
• タブ: w1:t1
• ペイン: w1:p1

閉じられたタブとペインの ID は再利用されません。別のワークスペースに移動されたペインには、新しいワークスペース修飾付きペイン ID が付与されます。pane move の後は、.result.move_result.pane.pane_id またはライブエージェント名で続行してください。古い値は .result.move_result.previous_pane_id として報告されます。移動されたプロセスの継承された呼び出し元コンテキストだけがその古い ID を解決し続けるため、一般的なエージェントのターゲットとして使用しないでください。

Herdr は各管理対象ペインに呼び出し元のコンテキストを注入します：

printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

ペインコマンドが呼び出し元のペインを対象とすべき場合は --current を優先してください。pane split のターゲットを省略した場合、HERDR_PANE_ID が利用可能であれば呼び出し元のペインを使用し、そうでなければフォーカスされたペインを使用します。他のコマンドは UI でフォーカスされているペインを使用する場合があり、それはユーザーまたは別のクライアントに属している可能性があります。

ライブ状態を確認するには：

herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent list

作成レスポンスは次に使用する ID を公開します。workspace create は .result.workspace、.result.tab、.result.root_pane を返します。tab create は .result.tab と .result.root_pane を返します。pane split は新しいペインを .result.pane として返します。

ID とライブエージェント名は 1 つのサーバーにスコープされます。保存された 2 つの SSH マシンがどちらも w1:p1 を持ったり、reviewer という名前のエージェントを持ったりする可能性があります。TUI でマシンを選択しても、ペインで実行中のコマンドのターゲットは変わりません。--machine を付けなければ、それらは依然として継承されたセッションとソケットのコンテキストを使用します。

保存された SSH マシンを制御するには、検出と以降のすべてのコマンドで同じグローバルプレフィックスを使用してください：

herdr --machine <label-or-id> agent list
herdr --machine <label-or-id> pane list
herdr --machine <label-or-id> agent prompt <remote-agent-name> "Reply with your current status." --wait --timeout 120000

セレクターは、有効な保存済みプロファイル ID、または一意で大文字と小文字を区別するラベルである必要があり、任意の SSH ホスト名ではありません。コマンドは、TUI を開かずにそのプロファイルのリモートセッションを使用します。--machine を --session または --remote と組み合わせないでください。そのマシン上で ID を検出してください。継承されたローカル ID と --current はリモートペインを識別しません。

両方のインストールがマシン API 転送をサポートしている必要があり、リモートサーバーはすでに実行中で API 互換である必要があります。転送はサーバーのインストール、起動、再起動を決して行わず、Local にフォールバックすることもありません。ローカル設定、セッション管理、インストールコマンド、対話的なアタッチは転送されません。リモートのワークツリーパスは絶対パス、~、または ~/ で始まる必要があり、プラグインのリンクパスは絶対パスでなければなりません。接続の失敗は、変更が適用されなかったことを証明するものではありません。再試行する前にリモートの状態を確認してください。

herdr machine list は保存された接続プロファイルを一覧表示するものであり、マシン間のペインインベントリではありません。スクリプトには --json を追加してください。プロファイルの追加、削除、有効化、無効化はユーザーが求めた場合にのみ行ってください。プロファイルを削除するとクライアントは切断されますが、リモートセッションは停止しません。対話的な machine add は実行中のリモートセッションを検出し、ユーザーに 1 つを選ぶよう求める場合があります。非対話的なセットアップでは、--remote-session が明示的に指定されない限り、リモートのデフォルトセッションを使用します。障害が発生しているマシンを診断するには herdr machine status [<label-or-id>] --json を使用してください。herdr machine reconnect はユーザーが自身のターミナルで SSH 認証を完了する必要があります。代わりに実行しないでください。セットアップは互換性のないサーバーを停止する前に確認を求め、デフォルトは No です。ユーザーの同意なしに置き換えを承認しないでください。実験的なハンドオフは machine add の一部ではありません。

エージェントを起動して調整する

デフォルトでは、現在のタブの隣接ペインと現在の作業ディレクトリを使用します。ユーザーが明示的にそのトポロジーや場所を要求しない限り、ワークスペース、タブ、ワークツリー、または別の cwd を作成しないでください。

ユーザーが要求した方向を尊重してください。それ以外の場合は、呼び出し元のペインを検査します。

herdr pane layout --pane "$HERDR_PANE_ID"

幅の広いペインは右に、幅の狭いまたは縦長のペインは下に分割します。使用できないほど狭い列や短い行を作成する、同じ方向への繰り返し分割は避けてください。ユーザーのフォーカスは呼び出し元のペインに保ち、呼び出し元の作業ディレクトリを明示的に維持します。

herdr pane split --current --direction right --cwd "$PWD" --no-focus

適切な場合は right を down に置き換えてください。新しいペイン ID は .result.pane.pane_id から読み取ります。

利用可能なシェルペインは、シェル自体がフォアグラウンドにあり、フォアグラウンドのコマンド、エディタ、エージェントが実行されていない、対話型プロンプトの状態でなければなりません。そのペインで、有用で一意な名前を付けてサポート対象のエージェントを起動します。

herdr agent start reviewer --kind codex --pane <returned-pane-id>

ユーザーが要求した kind を使用してください。インストールされている kind の一覧とオプションを確認するには herdr agent を実行します。ネイティブのエージェント引数は -- の後にのみ渡してください。

herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>

agent start の成功は、Herdr が同じペインで期待されるエージェントを検出し、対話型入力を受け付けられる準備ができたと判断した後にのみ返ります。起動中にエージェントがブロックされた場合、コマンドは直ちに agent_not_ready を返しますが、名前は agent read と agent send-keys で引き続き利用できます。エージェントにプロンプトを送る前に、エージェントがアイドル状態になるまで待ってください。起動時のタイムアウトはデフォルトで 30 秒です。

エージェントサーフェスを通じて作業を送信します。

herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000

agent prompt は、ペインの現在のブラケットペーストモードを尊重し、テキストとその後に続くエンコードされた Enter を 1 つの順序付けられた送信として送ります。送信の成功を報告するのは、両方が書き込まれた後のみです。それだけでは、エージェントがターンを開始したことを証明するものではありません。Windows 上の Codex では、Herdr は Enter の前にペースト境界を送るため、送信がプロンプトのサイズに依存しません。承認または質問ダイアログで既に待機しているエージェントに対しては、何も入力する前に agent_blocked を返して拒否します。ブロックされている UI を検査し、応答する前にユーザーに確認してください。通常のエージェント作業では --wait で十分です。これは最初に確定した idle、done、または blocked 状態を待ちます。これらのデフォルトを --until で繰り返さないでください。

--wait の場合、非作業状態から送信されたプロンプトは、観測された working または blocked のアクティビティを生み出す必要があります。送信後、Herdr はそのアクティビティを最大 5 秒間待ちます。無関係な idle、done、またはセッションの変化はこのゲートを満たしません。アクティビティが観測されない場合は agent_prompt_stalled を返し、呼び出し元のタイムアウトが先に切れた場合は timeout を返します。呼び出し元のタイムアウトには送信時間が含まれます。タイムアウトを指定しない場合、アクティビティが観測された後、確定状態の待機は無期限になります。この待機は個々のターンではなくライフサイクル状態を追跡します。エージェントが既に作業中であれば、アクティブなターンの完了がこれを満たす場合があります。

--until は、既に実行中のエージェントが入力を要求するのを待つ場合など、状態固有のワークフローにのみ使用してください。

herdr agent wait reviewer --until blocked --timeout 120000

--until を指定しない場合、単独の agent wait は agent prompt --wait と同じ確定状態のデフォルトを使用します。

対話型エージェント UI の操作には論理キーを使用します。

herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+c

Herdr は、バイトを書き込む前にすべてのキーを検証します。結果は解決されたエージェントを通じて読み取ります。

herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120

待機が失敗した場合、または blocked を返した場合は、どのような入力を送るかを決める前に agent get と agent read を検査してください。タイムアウトや停止した応答は、プロンプトが配信されなかったことを証明するものではありません。やみくもに再送信しないでください。ペインサーフェスは、生のターミナル制御を意図している場合にのみ使用してください。

別のペインで通常のコマンドを実行する

同じジオメトリ規則で兄弟ペインを作成し、呼び出し元の作業ディレクトリを保持して、ユーザーのフォーカスを変更しないようにします。

herdr pane split --current --direction right --cwd "$PWD" --no-focus

.result.pane.pane_id から新しいペイン ID を読み取り、コマンドを実行して結果を確認します。

herdr pane run <returned-pane-id> "just test"
herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120

pane run はコマンドテキストと Enter をまとめてキューに追加します。成功は受け付けられたことを示すものであり、コマンドの実行を示すものではありません。macOS では、ターミナルの現在の正規行入力制限を超えるコマンドは、キューに追加される前に pane run と agent start によって拒否されます。再試行する前に、対話型シェルのプロンプトが表示されるまで待ってください。このチェックの対象は今回の送信内容であり、それ以前の未完了行や、その後のターミナルモードの変更は対象外です。pane wait-output は選択したスナップショットをただちに検索するため、すでに存在する出力にも一致することがあります。リテラルな部分文字列には --match <text>、Rust の正規表現には --regex <pattern> を使用します。--timeout を省略すると、無期限に待機します。

タスクに合った読み取りソースを使用します。

• visible：現在描画されているビューポートです。
• recent：ソフトラップを含む、最近描画された出力です。
• recent-unwrapped：ソフトラップを結合した最近の出力です。ログやトランスクリプトにはこちらを推奨します。
• detection：エージェントの検出に使用される、バッファー下部のプレーンテキストのスナップショットです。

色やターミナルのスタイルが根拠となる場合は、--format ansi を使用します。それ以外の場合は text を使用します。

--lines を指定すると、Herdr はペインで利用可能な画面とホストのスクロールバックから、より多くの行を取得します。代替画面の行は通常のホストのスクロールバックには入りません。対応するアイドル状態のエージェントでは、Herdr はアプリケーションが管理する履歴を収集し、その後ビューポートを復元できますが、すべてのアプリケーションや応答をこの方法で復元できるわけではありません。

最近の出力をさらに読み取っても完了した応答が見つからない場合は、エージェントに一時ディレクトリ内の Markdown ファイルとして書き込み、そのファイルのパスだけを返信するよう依頼し、同じマシンでそのファイルを読み取ります。これはフォールバックとしてのみ使用し、最初のプロンプトでファイルへの出力を依頼しないでください。

安全性と連携に関するルール

• ユーザーがコンテキストの切り替えを依頼していない限り、バックグラウンド作業には --no-focus を使用します。
• --current、明示的なペイン ID、または一意のエージェント名を使用します。別のクライアントでフォーカスされているペインに依存しないでください。
• JSON レスポンスから ID を解析します。サイドバーの順序や例から ID を推測しないでください。
• ユーザーから明示的に依頼されていない限り、自分が作成していないワークスペース、タブ、ペイン、セッションを閉じないでください。通常の CLI/API による終了では、TUI の最後のペインに対する確認は引き継がれません。workspace close --group はプライマリワークスペースと、それにリンクされたワークツリーワークスペースを閉じます。workspace_group_close_required を回避するために、これを追加してはなりません。
• ユーザーがリポジトリを確認した後にのみ --trust-repository を使用します。これはリクエスト単位の Git 信頼を付与するものであり、失敗したワークツリーコマンドを再試行するために日常的に使用するものではありません。
• アップデート後にクライアントとサーバーのバージョンが異なることがあります。新しいサーバー機能に依存する前に、herdr status を確認してください。メソッドが存在しない場合でも、サーバーを停止またはアップグレードしてよいという意味ではありません。
• ユーザーがサーバーとそのペインプロセスを停止する意図を明示していない限り、アクティブなセッションから herdr server stop を実行してはなりません。
• Herdr のメインプロセスを終了してはなりません。分離されたサーバーが必要な実験には、名前付きテストセッションを使用します。
• CLI サーバーエラーは stderr に JSON で出力され、終了ステータスは 1 です。CLI 構文エラーの終了ステータスは 2 です。