AlexK-Notable/herdr-skill

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 を起動またはアタッチします。引数を省略して変更を伴うネストされたコマンドをプローブしないでください。herdr workspace create のようなコマンドはデフォルト値で有効であり、実行されます。

ほとんどの制御コマンドは JSON を返します。それらのレスポンスから ID と状態を読み取り、予測しないでください。

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

ジョブに合ったプリミティブを選択してください:

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

ペインは、エージェントが含まれていなくても存在します。agent start には既存の利用可能なシェルペインが必要であり、レイアウトを作成、分割、移動することはありません。通常のプロセスにはペインコマンドを使用してください。Herdr がエージェントの同一性を検証したり、idle、working、blocked、done、unknown のライフサイクル状態を解釈する必要がある場合は、エージェントコマンドを使用してください。

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

idle は、エージェントが入力を受け入れる準備ができており、そのタブがフォーカスされた Herdr UI で表示されたことを意味します。done は、表示されていないバックグラウンド作業が完了した後の、同じ基礎的なアイドル状態です。タブにフォーカスするか、ペインまたはエージェントをフォーカスコマンドでターゲットにすると、表示済みとマークされます。CLI 読み取りは表示済みとマークしません。blocked は、Herdr が承認または質問 UI を認識したことを意味します。unknown はエージェントが存在するが Herdr が確実に分類できないことを意味し、完了を証明するものではありません。

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

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

• workspace: w1
• tab: w1:t1
• pane: 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 を優先してください。ターゲットを省略すると 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 <返されたペインID>

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

herdr agent start reviewer --kind codex --pane <返されたペインID> -- <エージェント引数...>

agent start は、Herdr が同じペインで期待されるエージェントを検出し、対話型入力の準備ができたと見なした場合にのみ戻ります。デフォルトの起動タイムアウトは 30 秒です。

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

herdr agent prompt reviewer "現在の差分を確認し、実用的な指摘のみを報告してください。" --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

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

herdr pane run <返されたペインID> "just test"
herdr pane wait-output <返されたペインID> --match "test result" --timeout 120000
herdr pane read <返されたペインID> --source recent-unwrapped --lines 120

pane run はコマンドテキストと Enter をアトミックに送信します。pane wait-output は選択されたスナップショットを即座に検索するため、既に存在する出力も一致します。リテラル部分文字列には --match <text>、Rust 正規表現には --regex <パターン> を使用します。--timeout を省略すると無期限の待機が可能になります。

タスクに合った読み取りソースを使用してください:

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

色や端末スタイルが証拠となる場合は --format ansi を使用してください。それ以外の場合はテキストを使用してください。

--lines は、ペインの利用可能な画面およびホストスクロールバックからより多くの行を Herdr に要求します。増やしても完了した応答の一部がさらに表示されない場合、ペインはおそらく端末の代替画面でエージェントを実行しています。代替画面から出た行は Herdr のホストスクロールバックに入らないため、より大きな行数では回復できません。

その読み取りが失敗した後は、エージェントに完全な応答を一時ディレクトリに Markdown として書き込み、ファイルパスのみを返信するよう依頼し、ファイルを直接読み取ってください。これはフォールバックとしてのみ使用してください。最初のプロンプトでファイル出力を要求しないでください。

安全性と連携ルール

• ユーザーがコンテキストの切り替えを明示的に要求しない限り、バックグラウンド作業には --no-focus を使用します。
• --current、明示的なペイン ID、または一意のエージェント名を使用します。別のクライアントのフォーカスされているペインに依存しないでください。
• JSON レスポンスから ID を解析します。サイドバーの順序や例から導出しないでください。
• ユーザーが明示的に要求しない限り、自分が作成していないワークスペース、タブ、ペイン、またはセッションを閉じないでください。
• ユーザーがサーバーとそのペインプロセスを停止することを明示的に意図しない限り、アクティブなセッションから herdr server stop を実行しないでください。
• メインの Herdr プロセスを強制終了しないでください。分離されたサーバーが必要な実験には、名前付きテストセッションを使用してください。
• CLI サーバーエラーは、終了ステータス 1 で stderr に JSON として出力されます。CLI 構文エラーは終了ステータス 2 で終了します。

ローカルイディオム

上記の HERDR_ENV=1 ゲートは、ペイン内から現在のセッションを制御する場合に適用されます。ホストレベルの作業（設定の編集、プラグインのインストール、エージェント検出のデバッグ、ソケット/CLI を中心とした自動化の構築）は、任意のターミナルから正当に行えます。これらのタスクについては references/local-idioms.md を参照してください。通知配信の設定、エージェント検出のメンテナンス、Claude Code フックからのサイドバーメタデータ、イベントサブスクリプションパターン、ワークツリーフロー、プラグイン作成ノートが含まれています。