herdr

Herdr

Herdr の CLI はローカルソケットを介してターミナルペインを操作します。ネイティブのエージェント間通信や共有メモリは提供しません。Pi、Codex、Claude Code、Cursor CLI などのターミナルエージェントで動作します。ネイティブ連携により、検出精度、ステータスの正確性、セッションの復元機能が向上します。

前提条件

Ghostty の Herdr 内で制御するエージェントを実行してください。アクセス権とワークスペースの範囲を確認します。

test "${HERDR_ENV:-}" = "1"
test -n "${HERDR_WORKSPACE_ID:-}"

いずれかに失敗した場合は、このエージェントを Herdr 内で起動する必要があることをユーザーに伝えてください。他のエージェントにアクセスできると主張してはいけません。

初回のみのインストール：

npx skills add ogulcancelik/herdr --skill herdr -g

調査、メッセージ送信、待機、読み取り

すべての Herdr コマンドに --session <name> を追加してください。HERDR_SESSION だけを指定すると、すでに実行中のサーバーが気づかないうちに選択されることがあります。ペイン ID を調べてください。推測してはいけません。

herdr pane list --workspace "$HERDR_WORKSPACE_ID" --session <name>
herdr pane read <pane-id> --source recent-unwrapped --lines 200 --session <name>

# For TUI agent composers, separate text from Enter
herdr pane send-text <pane-id> "Check the failing tests and report back." --session <name>
sleep 1
herdr pane send-keys <pane-id> enter --session <name>

# Confirm submission, then wait for completion (idle if the integration uses it)
herdr agent wait <pane-id> --status working --timeout 120000 --session <name>
herdr agent wait <pane-id> --status done --timeout 120000 --session <name>
herdr pane read <pane-id> --source recent-unwrapped --lines 200 --session <name>

現在のワークスペース内にとどまってください。メッセージを送る前に読み取ってください。調査のみの依頼には何も送信しないでください。Enter の後、ペインの内容が変わっただけで判断せず、ネイティブステータスが working／blocked に遷移したことを確認してください。done、idle、または blocked になるまで待ってから、再度読み取ってください。プロンプトが実行されたと決めつけてはいけません。以下の説明に従い、ペインのテキストと照合して idle を確認してください。

エージェント間を調整する場合は、不足しているコンテキストを共有し、作業の重複を防ぎ、統合した要約を 1 つ返してください。

自分が作成していないペインを閉じたり、名前変更、移動、サイズ変更、再設定したりしてはいけません。ユーザーから明示的に依頼された場合にのみ、ペインを作成または閉じてください。「Herdr スキルを使う」とは、CLI のワークフローを実行することであり、説明するだけではありません。

運用の詳細

セッションとターゲット指定

• 破壊的な操作には、名前付きの herdr session stop <name>／herdr session delete <name> を使ってください。herdr server stop は環境内のサーバーを対象とするため、使用してはいけません。
• ターゲットは <session>:<pane-id> です。ペイン ID にはコロン（w1:p2）が含まれます。分割するのは最初のコロンだけです。
• CLI の呼び出しではサーバーは自動起動しません。herdr server --session <name> でヘッドレス起動してください。
• 管理対象のプロセスには HERDR_ENV=1 と HERDR_PANE_ID が設定されます。ネストされた tmux 内では $TMUX が優先されます。そのペインは tmux として扱ってください。
• リスクのある実験には、default ではなく、分離された名前付きセッションを使ってください。停止または削除する直前に、herdr session list --json --session <name> を再確認してください。

入力

• pane send-text は送信せずにテキストを入力します。pane run はテキストと Enter を送信するため、シェルのプロンプトでは機能しますが、TUI の入力欄（Claude Code、Cursor CLI）では貼り付けの一部として Enter が処理されることがあります。TUI では send-text を実行し、約 1 秒待ってから send-keys <pane> enter を別途実行してください。
• C0 制御バイト（例：ASCII 0x1f）はターミナル操作を引き起こし、入力済みテキストを消去することがあります。不可視のテキストマーカーには U+2063 INVISIBLE SEPARATOR を使ってください。
• スラッシュコマンドのオートコンプリートでは、最初の Enter がポップアップを閉じたり、引数のプレースホルダーを埋めたりするために消費されることがあります。escape を押すと、テキストを保持したままポップアップを閉じられます。

読み取りとステータス

• pane read --lines N は、N がビューポートの高さを下回ると空の出力を返します。少なくとも 200 行、かつビューポートの高さ以上を指定し、tail -n N を使ってローカルで切り詰めてください。
• pane get の .cwd は作成時点の値で固定されます。.foreground_cwd は現在の値です。
• プレースホルダーテキストと人が入力した下書きを区別するには、pane read --format ansi を使ってください。提案は暗く表示され（SGR-2 または暗いトゥルーカラー）、入力したテキストは通常どおり表示されます。プレーンテキストでは確実に区別できません。
• herdr agent get <pane> は、ネイティブの working／idle／done／blocked／unknown ステータスを報告します。正規表現による推測よりもこちらを優先してください。実行時間の長いフォアグラウンドツールでも idle と報告されることがあります。ペインが空いている、または古いと判断する前に、「esc to interrupt」などのビジーバナーを確認してください。
• ネイティブの待機コマンド：herdr agent wait <pane> --status <s> --timeout MS、herdr wait agent-status <pane> --status <s> --timeout MS、および herdr wait output <pane> --match <text>。
• ソケットプロトコル >=16 では、pane.agent_status_changed イベントと pane.output_matched イベントが利用できます。イベントを優先し、ポーリングはバックストップとして使ってください。
• スクリプトは pane report-agent を使って登録し、idle／working／blocked を報告できます。

ワークスペースとタブのライフサイクル

• ラベルは一意ではありません。重複がないか自分で確認してください。ラベルで検索すると、最初に一致したものが選択されます。ラベルのないワークスペースには cwd のベース名が表示されますが、明示的に設定したラベルと重複することがあります。
• workspace create はタブ 1 を作成します。最後のタブを閉じるとワークスペースが削除され、タブの唯一のペインを閉じるとタブが閉じます。
• 空のセッションで最初のワークスペースを作成する場合を除き、ワークスペースやタブの作成では --no-focus が尊重されます。pane split --no-focus を使ってもホストのビューポートは縮小されます。フォーカスとジオメトリは別々です。
• 名前付きセッションを再起動すると ID とラベルは保持されますが、プロセスやエージェントの登録は保持されません。復元されたペインは新しいシェル（agent_not_found）であり、稼働中の重複ではありません。上記のペイン権限の範囲内でのみ閉じて置き換えてください。

その他の詳細

• pane run から起動したスクリプトでは、レイアウトの取得に tput cols を使わないでください。古いデフォルト値の 80 を返すことがあります。
• herdr integration install <harness>（claude、codex、cursor、pi、...）を実行すると、ネイティブのステータス検出が有効になります。herdr notification show <title> はアラートを表示します。

ユーザーが求めた場合にのみエージェントを起動する

必ず自動承認付きでエージェントを起動してください。そうしないと、無人のワーカーが未回答のプロンプトで停止することがあります。

• Cursor CLI：cursor-agent --yolo "task"（--force のエイリアス）
• Codex CLI：codex --yolo "task"
• Claude Code：claude --dangerously-skip-permissions "task"

これは、すべてのエージェントに適切な拒否リストフックがインストールされていることを前提としています。初回起動時に信頼確認ダイアログが表示されることがあります。起動後にペインを確認してください。ネイティブのステータス検出を有効にするには、各インテグレーションを一度インストールしてください。

herdr agent wait <pane> --status working --timeout MS または herdr wait output <pane> --match <text> で起動を確認してから、読み取ってください。起動確認に sleep N && pane read は使用しないでください。前述の短い入力送信待機時間とは目的が異なります。

Cursor CLI

スクリプトでは cursor-agent を使用してください。agent はエイリアス／新しいドキュメント上の名前です。David が対話形式で使う cur の略記は cursor-agent --yolo に展開されますが、スクリプトではエイリアスは展開されません。

既存のシェルペインで起動する前に、cursor-agent --list-models で利用可能なモデルのスラッグを確認してください。

herdr pane run <pane-id> "cd <worktree> && cursor-agent --model <verified-model-slug> --yolo 'fix the failing tests'" --session <name>

• 対話形式： cursor-agent "task"、または空のセッションで引数なし。ヘッドレス： cursor-agent -p "task" --output-format text|json|stream-json。
• 権限： --force／--yolo はコマンドごとの承認を省略します。--sandbox enabled|disabled はサンドボックスを制御します。スクリプトでの認証には CURSOR_API_KEY を使用します。
• モデル： 起動時は --model <slug>、セッション中は /model を使用します。スラッグはバージョンやアカウントによって異なるため、記憶を頼りに決めつけないでください。
• 推論の強度： --effort フラグはありません。末尾が -low、-medium、-high、または -xhigh の完全なスラッグを使用してください（例：gpt-5.3-codex-xhigh、claude-opus-4-8-thinking-high）。-fast は速度を制御するもので、推論の強度には影響しません。--help に記載されていても、model[effort=high] はサポートされていません。
• 一部のビルドでは、--model の推論サフィックスが黙って無視されます。起動後に /model で確認してください。--disable-auto-update を指定すると、動作するビルドを維持できます。
• 再開： cursor-agent resume（最新のチャット）、--resume <chatId>、または一覧表示するには cursor-agent ls を使用します。

直接ショートカット

ほとんどのデフォルト設定では Ctrl+B を使用します。Ctrl+Alt の直接ショートカットは、競合することがほとんどありません。~/.config/herdr/config.toml に追加してください。

[keys]
new_workspace = "ctrl+alt+n"
workspace_picker = "ctrl+alt+w"
goto = "ctrl+alt+g"
new_tab = "ctrl+alt+c"

次のコマンドで適用します。

herdr server reload-config --session <name>

異なるプレフィックスを使いながらプレフィックス付きショートカットを維持するには、[keys] の下に prefix = "ctrl+a" を設定してください。