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 を単独で実行しないでください。TUI が起動するか、TUI に接続されます。引数を省略して、変更を伴うネストされたコマンドを試さないでください。herdr workspace create などのコマンドは、デフォルト値で有効に実行されます。

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

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

作業に合った基本要素を選んでください。

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

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

エージェントコマンドでは、一意の稼働中エージェント名、またはそのエージェントを現在ホストしているペイン ID を指定できます。ターミナル ID やエージェント種別のラベルだけでは指定できません。名前は [a-z][a-z0-9_-]{0,31} に一致し、稼働中のエージェント間で一意である必要があります。名前は現在のペインの占有者に追従し、そのエージェントが終了、解放、または置換されるとクリアされます。

idle は、エージェントが入力を受け付けられる状態であり、そのタブがフォーカス中の Herdr UI で確認済みであることを意味します。done は、未確認のバックグラウンド作業が終了した後の、同じ基盤となるアイドル状態です。タブにフォーカスするか、フォーカスコマンドでペインまたはエージェントを対象にすると、確認済みとして記録されます。CLI による読み取りでは、確認済みとして記録されません。blocked は、Herdr が承認画面または質問画面を認識したことを意味します。unknown はエージェントが存在するものの、Herdr が確信を持って分類できないことを意味し、完了を示すものではありません。

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

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

• workspace：w1
• tab：w1:t1
• pane：w1:p1

閉じたタブ ID とペイン 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 を優先してください。対象を省略すると、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 として返します。

エージェントを起動して連携する

デフォルトでは、現在のタブと現在の作業ディレクトリで、同じタブ内の隣接ペインを使用します。ユーザーが明示的に別の構成や場所を指定しない限り、ワークスペース、タブ、ワークツリーを作成したり、異なる作業ディレクトリを使用したりしないでください。

ユーザーが指定した方向に従ってください。指定がない場合は、呼び出し元のペインを確認します。

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>

ユーザーが指定した種類を使用してください。herdr agent を実行して、インストール済みの種類とオプションを確認します。ネイティブエージェントの引数は -- の後にのみ指定してください。

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

agent start は、Herdr が同じペイン内で想定されたエージェントを検出し、対話型入力を受け付けられる状態になったと判断した後にのみ戻ります。起動タイムアウトのデフォルトは 30 秒です。

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

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

agent prompt は、ペインの現在のブラケット付きペーストモードに従いながら、テキストとエンコードされた Enter キーをアトミックに送信します。通常のエージェント作業では、--wait だけで十分です。これは最初に idle、done、または blocked の状態が確定するまで待機します。--until でこれらのデフォルトを繰り返し指定しないでください。

作業中でない状態から送信されたプロンプトでは、5 秒以内に観測可能なライフサイクルの変化が発生する必要があります。そうでない場合、Herdr は無期限に待機する代わりに agent_prompt_stalled を返します。この待機が追跡するのはライフサイクルの状態であり、個々のターンではありません。エージェントがすでに作業中の場合、アクティブなターンの完了によって条件が満たされることがあります。

実行中のエージェントが入力を求めるのを待つ場合など、特定の状態を待つワークフローに限り、--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 をアトミックに送信します。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 を推測しないでください。
• ユーザーが明示的に依頼しない限り、自分が作成していないワークスペース、タブ、ペイン、セッションを閉じないでください。
• ユーザーがサーバーとそのペインプロセスの停止を明示的に意図していない限り、アクティブなセッションから herdr server stop を実行しないでください。
• メインの Herdr プロセスを終了しないでください。サーバーを分離して実験する必要がある場合は、名前付きのテストセッションを使用してください。
• CLI のサーバーエラーは、終了ステータス 1 とともに stderr に JSON で出力されます。CLI の構文エラーの終了ステータスは 2 です。