| name | herdr |
| description | Use when creating or editing herdr configuration (`~/.config/herdr/config.toml`) — keybindings, themes, UI/sidebar, notifications, sounds, terminal defaults, worktrees, or experimental options — when herdr shows a startup config warning, or when inspecting or controlling live Herdr workspaces, tabs, and panes through the CLI, including launching an interactive command or TUI in a specific tab. Do not use for generic terminal multiplexer comparisons. |
Herdr Configuration and Runtime Control
herdr は tmux 風 prefix モードを持つ agent-multiplexer TUI。設定は単一の TOML ファイルで管理し、live workspace / tab / pane は socket API の CLI helper で操作する。
Key facts
- 設定ファイル:
~/.config/herdr/config.toml（HERDR_CONFIG_PATH で上書き可）
- デフォルト全設定の出力:
herdr --default-config
- 反映:
herdr server reload-config（再起動不要。startup-only 設定のみ再起動が必要）
- 不正な値は安全なデフォルトに fallback し、startup warning が出る。warning は
~/.config/herdr/herdr-server.log で確認する
- キーバインドをデフォルト（v2）へ戻す:
herdr config reset-keys（config.toml をバックアップして [keys] / [[keys.command]] を除去）
Configuration workflow
- 既存 config を読む —
~/.config/herdr/config.toml を必ず先に読む。コメントに書かれた規約（prefix 選定、Ghostty 互換バインド、JIS キーボードの ¥ 扱いなど）はユーザーの設計判断であり、編集時に必ず維持する。
- 設定項目を確認する — 対象セクションの仕様は references/configuration.md を参照。載っていない項目・挙動が疑わしい項目は https://herdr.dev/docs/configuration/ の現行ドキュメントを取得して確認する（herdr はバージョンで設定面が変わる。
herdr --version で確認）。
- 編集する — 既存のセクション順・コメントスタイルを保って編集する。新規作成時は
herdr --default-config を起点にせず、ユーザーが求めた項目だけを書く（herdr は未指定項目をデフォルトで補う）。
- 反映と検証 —
herdr server reload-config を実行し、herdr-server.log の末尾に新しい config warning が出ていないことを確認して完了。warning が出た場合は該当値を修正して再実行する。
Runtime workspace, tab, and pane control
既存の Herdr セッションで特定 workspace / tab / pane を操作するときは、TUI へキー入力を推測で送らず socket API helper を使う。
herdr status で server の稼働状態を確認する。herdr workspace list、herdr tab list --workspace <workspace_id>、herdr pane list --workspace <workspace_id> の順で対象 ID を特定する。ユーザーが「3 タブ目」のように指定した場合は workspace 内の label / 表示順を照合し、raw number が workspace 内の連番だと仮定しない。herdr pane process-info --pane <pane_id> で foreground process を確認する。shell が待機中の pane にだけコマンドを起動し、agent や別 TUI が動作中なら上書きせず、別 pane の選択・作成またはユーザー確認へ切り替える。herdr pane run <pane_id> "cd <absolute-cwd> && <command>" で対象 pane にコマンドを起動する。hunk diff や lazygit などの interactive TUI も agent 自身の PTY ではなく、ユーザーが見る Herdr pane で起動する。- 必要なら
herdr tab focus <tab_id> で対象 tab を表示する。
herdr pane process-info --pane <pane_id> を再実行し、期待した foreground process と cwd になったことを確認する。
例: 指定した worktree の Hunk review を対象 tab で開始する。
herdr pane run <pane_id> "cd /absolute/path/to/worktree && hunk diff"
herdr tab focus <tab_id>
herdr pane process-info --pane <pane_id>
client / server の互換性エラーで操作できない場合も、稼働中セッションを中断し得る server restart は自動実行しない。herdr status の結果と失敗したコマンドを報告して確認を取る。
Keybinding safety rules
キーバインドは prefix-first が原則。直接ショートカットはシェルや TUI から入力を奪う。
prefix+n = prefix を押してから n。ctrl+alt+n = 直接ショートカット。プレーンな印字キー単独（"n" など）は入力を横取りするため禁止 — 意図的な直接バインド以外は必ず prefix+ を付ける- 例外:
navigate_workspace_* / navigate_pane_* は navigate-mode 専用でプレーンキー可（j, k など）。ただし prefix+, esc, enter, tab, shift+tab, left, right, 無修飾 1–9 は使えない
- 1つのアクションに複数キーを配列で割当可:
next_tab = ["prefix+n", "ctrl+alt+]"]
- インデックスバインドは
1..9 表記: switch_tab = "prefix+1..9"（legacy [keys.indexed] は使わない）
- バインドを外すときは空文字列
"" を代入する
- デフォルトキーを別アクションに割り当てるときは、元のアクションの退避先を検討する（例:
prefix+o を cycle_pane_next に使うなら open_notification_target を別キーへ）
キー文字列は ctrl+a / shift+n / alt+1 / cmd+k、特殊キー enter tab esc left 等、名前付き記号 minus comma plus backtick 等を受け付ける。JIS キーボードの ¥ は shift なしで U+00A5 を送るため、| ではなく ¥ そのものでバインドする。
Custom command keybindings
[[keys.command]]
key = "prefix+alt+g"
type = "pane"
command = "lazygit"
description = "run lazygit"
コマンドには HERDR_SOCKET_PATH, HERDR_ACTIVE_PANE_CWD などの環境変数が渡る。詳細は references/configuration.md。
