# Herdr クイックリファレンス

*workspace、pane、エージェント状態、CLI 自動化（v0.9.x）*

> Source: Herdr documentation (herdr.dev, v0.9.3) and herdr CLI help output · MIT

## メンタルモデル

### レイヤー

| Command | Description |
|---------|-------------|
| `session` | バックグラウンドサーバーの名前空間。全プロセスを保持 |
| `workspace` | リポジトリ／タスクごとに 1 つ。サイドバーで状態を集約 |
| `tab` | workspace 内のレイアウト（エージェント、ログ、サーバー） |
| `pane` | 実際のターミナル。右／下に分割、デタッチ後も存続 |
| `agent` | Herdr が pane 内で認識するコーディングエージェント |

*クライアントをデタッチしてもサーバーと全 pane は動作し続ける*

### エージェントの状態

| Command | Description |
|---------|-------------|
| `working` | エージェントがターンを処理中 |
| `blocked` | 承認プロンプトまたは質問への応答待ち |
| `done` | 完了したが、まだ確認していない |
| `idle` | 完了または待機中で、確認済み |
| `unknown` | エージェントはいるが状態不明。完了の証拠ではない |

*idle と done はどちらも新しいプロンプトを受け付ける状態*

### 入力モード

| Command | Description |
|---------|-------------|
| `terminal` | キー入力はフォーカス中の pane に直接送られる |
| `prefix` | Ctrl-b の後、次のキーが Herdr のアクションになる |
| `navigate` | 常駐する workspace ナビゲーション画面 |
| `copy` | キーボードでスクロールバック・検索・選択（Prefix [） |

## はじめに

### インストールと起動

```
curl -fsSL https://herdr.dev/install.sh | sh
cd ~/projects/app
herdr           # launch or attach
claude          # any agent, auto-detected
herdr update    # self-update
herdr status    # client vs server version
```

### エージェント連携

```
herdr integration install claude
herdr integration install codex
herdr integration status --outdated-only
```

*連携により正確な状態を報告し、サーバー再起動後もエージェントを再開可能*

### マウス優先

> すべてクリック可能：pane、tab、workspace、エージェント行。境界のドラッグでリサイズ、右クリックで分割・tab メニュー、ドラッグ選択でコピー。キー操作は任意の追加レイヤー。

## キーバインド

### まず覚えるキー

| Command | Description |
|---------|-------------|
| `Prefix ?` | 有効なバインドをすべて表示（/ で絞り込み） |
| `Prefix c` | 新しい tab |
| `Prefix v` | 分割：右に新しい pane |
| `Prefix -` | 分割：下に新しい pane |
| `Prefix h/j/k/l` | 左／下／上／右の pane にフォーカス |
| `Prefix w` | workspace ナビゲーション |
| `Prefix q` | デタッチ。すべて動作し続ける |

*デフォルトのプレフィックスは Ctrl-b。デタッチは tmux の d ではなく q*

### Pane

| Command | Description |
|---------|-------------|
| `Prefix z` | フォーカス中の pane をズーム（全画面） |
| `Prefix x` | pane を閉じる |
| `Prefix Shift-h/j/k/l` | 隣の pane と入れ替え |
| `Prefix r` | リサイズモード |
| `Prefix Tab` | 次の pane へ順番に移動 |
| `Prefix Shift-p` | pane の名前を変更 |
| `Prefix e` | スクロールバックをエディタで開く |

### Tab と Workspace

| Command | Description |
|---------|-------------|
| `Prefix n / p` | 次／前の tab |
| `Prefix 1..9` | 番号で tab にジャンプ |
| `Prefix Shift-t / Shift-x` | tab の名前変更／閉じる |
| `Prefix Shift-n` | 新しい workspace |
| `Prefix Shift-g` | git worktree 上に新しい workspace |
| `Prefix Shift-w / Shift-d` | workspace の名前変更／閉じる |
| `Prefix g` | Goto ピッカー：全エージェントとターミナル |
| `Prefix o` | 最新の通知の pane にジャンプ |
| `Prefix b` | サイドバーの表示切り替え |
| `Prefix s` | 設定 |

*Goto ピッカーでは b/w/i/d で blocked/working/idle/done を絞り込み、/ で検索*

### コピーモード（Prefix [）

| Command | Description |
|---------|-------------|
| `h/j/k/l  w/b/e` | 文字または単語単位で移動 |
| `Ctrl-u / Ctrl-d` | 半ページ上／下 |
| `/  ?  n  N` | 前方／後方検索、繰り返し |
| `v or Space` | 選択を開始 |
| `y or Enter` | 選択範囲をコピーして終了 |
| `q or Esc` | コピーせずに終了 |

*スクロールバック中も pane は動作し続ける*

## Session とリモート

### 永続化

```
herdr                      # reattach
herdr session list
herdr session attach work  # isolated server
herdr session stop work
herdr server stop          # kills ALL panes
```

### SSH 経由

```
herdr --remote workbox  # local UI, remote panes
herdr --remote workbox --session agents
herdr machine add workbox --label box
herdr --machine box agent list
```

### Worktree としての Workspace

```
herdr worktree create --branch fix/login --base main
herdr worktree list
herdr worktree remove --workspace w3
```

## Pane のスクリプト操作

### ID とコンテキスト

> ID の形式は w1（workspace）、w1:t1（tab）、w1:p1（pane）。Herdr の pane 内では HERDR_ENV=1 と HERDR_PANE_ID が設定される。コマンドは JSON を返す：新しい ID はレスポンスから読み取り、サイドバーの順序から推測しないこと。

### 一覧取得

```
herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr pane layout --current
```

### 隣の pane でコマンド実行

```
id=$(herdr pane split --current \
       --direction right --no-focus \
     | jq -r .result.pane.pane_id)
herdr pane run "$id" "npm test"
herdr pane wait-output "$id" \
  --match "passed" --timeout 120000
herdr pane read "$id" --lines 80 \
  --source recent-unwrapped
```

### Pane コマンド

| Command | Description |
|---------|-------------|
| `pane run ID CMD` | コマンド入力と Enter を一度に実行 |
| `pane send-text ID TEXT` | テキストをそのまま入力（Enter なし） |
| `pane send-keys ID ctrl+c` | 名前付きキーを送信 |
| `pane wait-output --regex RE` | 出力が一致するまで待機（Rust 正規表現） |
| `pane zoom ID --toggle` | スクリプトから pane をズーム |
| `pane move ID --new-tab` | pane を移動。新しい ID が割り当てられる |
| `notification show TITLE` | トースト通知を表示（--sound done も可） |

## エージェントのオーケストレーション

### 起動・プロンプト・回収

```
herdr agent start reviewer --kind codex --pane "$id"
herdr agent prompt reviewer "Review the diff" \
  --wait --timeout 300000
herdr agent read reviewer --lines 120
herdr agent wait reviewer --until blocked
herdr agent send-keys reviewer esc
```

### Agent コマンド

| Command | Description |
|---------|-------------|
| `agent list` | 稼働中の全エージェントと状態 |
| `agent get NAME` | エージェントの pane、種類、状態 |
| `agent focus NAME` | UI をそのエージェントへ移動（確認済みにする） |
| `agent attach NAME` | Herdr UI なしでそのターミナルだけを開く |
| `agent explain NAME` | 検出がこの状態を選んだ理由 |

*対象は一意のエージェント名、またはそれを含む pane の ID*

### Pane と Agent コマンドの比較

| Choice | Use when | Watch for |
|--------|----------|-----------|
| `pane` | シェル、テスト、サーバー | エージェントの状態を認識しない |
| `agent` | 検出済みのコーディングエージェント | blocked のエージェントは拒否 |

### 経験則

> agent start にはシェルプロンプト状態の既存 pane が必要で、レイアウトは作成しない。バックグラウンド作業には --no-focus を使う。タイムアウト後は再送の前にエージェントを read すること：プロンプトがすでに届いている可能性がある。

## 設定

### ~/.config/herdr/config.toml

```
[keys]
prefix = "ctrl+a"
focus_pane_left = ["prefix+h", "ctrl+alt+h"]
[theme]
name = "tokyo-night"
[ui.toast]
delivery = "system"  # or herdr / terminal
```

### カスタムポップアップコマンド

```
[[keys.command]]
key = "prefix+alt+g"
type = "popup"       # or "pane" / "shell"
command = "lazygit"
width = "80%"
height = "80%"
```

### 設定コマンド

| Command | Description |
|---------|-------------|
| `herdr --default-config` | 全オプションをコメント付きで出力 |
| `herdr config check` | config.toml を検証 |
| `Prefix Shift-r` | 実行中のサーバーで設定を再読み込み |
| `herdr config reset-keys` | 設定をバックアップし、カスタムバインドを削除 |

*prefix なしのバインドには ctrl+alt の組み合わせが最も安全（ターミナル間で互換）*