kitherd

Kitty を使用した Headless Herdr

このスキルでは、Herdr をヘッドレスのバックグラウンドプロセスマネージャーとして、Kitty をネイティブ GUI ウィンドウマネージャーとして使用し、AI コーディネーター（マスター）エージェントがワーカーエージェントを管理する方法を説明します。

このアーキテクチャでは：

• ヘッドレス Herdr サーバー（default セッション）： バックグラウンドデーモン（Linux では systemd サービス、macOS では launchd エージェント）として実行されます。ペイン、ターミナルエミュレーター、エージェントプロセス、永続的なライフサイクルを、対話型 TUI なしで管理します。
• Kitty ターミナル： 視覚的なインターフェイスとして機能します。マルチプレクサーの UI を実行する代わりに、kitty @ launch ... herdr agent attach <name> を使用して、ネイティブな Kitty の分割ウィンドウとタブからワーカーエージェントを表示します。Kitty の分割ウィンドウを閉じても表示が切り離されるだけで、ワーカーエージェントはバックグラウンドで実行を続けます。
• 対話型スイッチャー（herdr_panel.py）： ユーザーは、リアルタイムのステータスとともにすべてのエージェントを一覧表示する対話型 fzf パネルを開き、定義されたキー割り当てでエージェントに接続したり、終了したりできます。

---

オーケストレーションの基本ルール

1. デフォルトセッションを対象にする： --session <name> を付けずに、常にプレーンな herdr コマンドを使用してください。名前付きセッションは対話型 TUI ワークフロー用です。明示的な指示がない限り、ヘッドレスワーカーを名前付きセッション内に作成しないでください。

2. マスターとワーカーの厳格な階層構造： マスターエージェントは、ワーカーエージェントの起動、プロンプト送信、監視、停止を担う唯一のコーディネーターです。ワーカーが他のエージェントを起動または制御することは絶対に避けてください。再帰的またはピア間のエージェント起動は意思決定ツリーを不明瞭にし、連携を損ないます。

3. Herdr の環境ガード： 標準の Herdr スキルにおける HERDR_ENV=1 ガードは、ヘッドレスのデフォルトセッションではなく、対話型 TUI ペインに適用されます。どのシェルからでも安全に herdr CLI コマンドを実行できます。マスターは管理対象の Herdr ペインの外部で実行されるため、--current と $HERDR_PANE_ID は使用できません。必ず明示的なペイン ID または一意のエージェント名を指定してください。

4. ワークスペースによるディレクトリの分離： 各プロジェクトディレクトリには、専用の Herdr ワークスペースが必要です。同じプロジェクトの複数のワーカーは、そのワークスペースを共有します。同時実行中のコンテキスト汚染を防ぐため、異なるリポジトリやプロジェクトのワーカーを同じワークスペースに混在させないでください。

5. --cwd には絶対パスを必ず指定する： すべての workspace create、tab create、pane split で --cwd は必須です。絶対パスを指定してください（現在のプロジェクトルートには "$PWD" を使用します）。Herdr CLI は呼び出し元の作業ディレクトリを自動的に引き継ぎません。--cwd を省略すると、新しいペインは直前にフォーカスされていたワークスペースを引き継ぐか、$HOME に戻ります。エージェントを起動する前に、JSON レスポンスの cwd フィールドを確認してください。

6. Kitty のリモート起動では環境と作業ディレクトリをそろえる（--copy-env と --cwd）： Kitty で kitty @ launch を使用してウィンドウまたはタブを開く場合は、必ず --copy-env と --cwd="$PWD" の両方を指定してください：

   kitty @ launch --type=window --location=vsplit --copy-env --cwd="$PWD" herdr agent attach <worker-name>
   

   • --copy-env：Kitty の GUI プロセスは、systemd、launchd、またはデスクトップマネージャーによって最小限の環境で起動されます。--copy-env は、アクティブなシェル環境（PATH、API キー、仮想環境、direnv）を引き継ぎます。
   • --cwd="$PWD"：Kitty ウィンドウコンテナーの作業ディレクトリを設定します。これがない場合、その Kitty ウィンドウ内で作成される新しい分割ウィンドウ（alt+enter）、タブ、または補助ターミナルの作業ディレクトリは、デフォルトで $HOME になります。注：herdr agent attach はシェルではなくクライアントプロキシであるため、Kitty の --cwd=last_reported ではエージェントのディレクトリを自動検出できません。

7. タブより分割ウィンドウを優先する： 新しいワーカーエージェントを表示するときは、ユーザーが進行状況を並べて確認できるよう、常に Kitty の垂直分割（--location=vsplit）をデフォルトにしてください。水平分割（--location=hsplit）またはタブ（--type=tab --tab-title <worker-name>）は、依頼があった場合、または画面領域が限られている場合にのみ使用してください。

---

手順

ステップ 1：プロジェクトのワークスペースがあることを確認する

アクティブなワークスペースを確認します：

herdr workspace list

プロジェクトディレクトリ（"$PWD"）に対応するワークスペースがない場合は、作成します：

herdr workspace create --cwd "$PWD" --label "<project-name>" --no-focus

.result.workspace.workspace_id から workspace_id（例：w1）を解析します。

ステップ 2：ワーカー専用のタブ／ペインを作成する

プロジェクトのワークスペースに新しいタブを作成します。

herdr tab create --workspace <workspace-id> --cwd "$PWD" --label "<worker-name>" --no-focus

JSON レスポンスの .result.root_pane.pane_id から pane_id を取得します（例：w1:p2）。.result.root_pane.cwd がプロジェクトのパスと一致することを確認します。

ステップ 3：ペインでエージェントを起動する

新しく作成したペインでワーカーエージェントを起動します。

herdr agent start <worker-name> --kind <kind> --pane <pane-id> -- <agent-args...>

• 対応している --kind の値は、claude、codex、copilot、opencode、agy、pi、gemini、cursor、amp、cline、omp、devin などです。
• エージェント固有のフラグは -- の後に渡します（例：--dangerously-skip-permissions や --model ...）。
• herdr agent start は、Herdr が対話型エージェントの起動を検知し、アイドル状態で応答可能なプロンプトに達するまでブロックします。

ステップ 4：Kitty で画面を開く

エージェントを表示するため、Kitty の分割画面を接続します。

kitty @ launch --type=window --location=vsplit --copy-env --cwd="$PWD" herdr agent attach <worker-name>

水平分割するには、--location=hsplit を使用します。新しいタブを作成するには、--type=tab --tab-title <worker-name> を使用します。

ステップ 5：連携、プロンプトの送信、監視

ワーカーに指示を送信します。

herdr agent prompt <worker-name> "<instruction-text>" --wait

• --wait：エージェントがアイドル、完了、またはブロック状態に戻るまで待機します。
• フリート全体のステータスはいつでも確認できます。

  herdr agent list
  

ステップ 6：ブロックされたエージェントと承認への対応

herdr agent list でエージェントのステータスが blocked と報告された場合：

1. ターミナル画面を確認し、エージェントが求めている内容を把握します。

   herdr agent read <worker-name> --source visible
   

2. Claude Code の使用時は注意してください： Claude Code のインライン自動提案（入力欄に表示されるゴーストテキスト）により、エージェントが実際にはアイドル状態であるにもかかわらず、Herdr の検出機能が blocked と報告することがあります。プロンプトに応答する前に、必ず herdr agent read で確認してください。
3. 必要な確認応答またはキーを送信します。

   herdr agent send-keys <worker-name> y
   herdr agent send-keys <worker-name> enter
   

ステップ 7：終了とクリーンアップ

ワーカーが割り当てられたタスクを完了し、不要になったら：

1. サーバー上の Herdr ペインを閉じます。

   herdr pane close <pane-id>
   

2. 関連付けられたプロセスが終了すると、対応する Kitty の分割画面またはウィンドウも自動的に終了します。

---

CLI コマンド早見表

操作	コマンド
ワークスペースの一覧表示	herdr workspace list
ワークスペースの作成	herdr workspace create --cwd "$PWD" --label <name> --no-focus
タブ／ペインの作成	herdr tab create --workspace <ws> --cwd "$PWD" --label <name> --no-focus
エージェントの起動	herdr agent start <name> --kind <kind> --pane <pane-id> -- <args>
Kitty で画面を接続	kitty @ launch --type=window --location=vsplit --copy-env --cwd="$PWD" herdr agent attach <name>
エージェントへのプロンプト送信	herdr agent prompt <name> "<prompt>" --wait
フリートのステータス確認	herdr agent list
エージェントの出力を読み取る	herdr agent read <name> --source visible （または --source recent-unwrapped）
エージェントにキーを送信	herdr agent send-keys <name> <key>
ペインを閉じる	herdr pane close <pane-id>