.dotfile/herdr/README.md

herdr

个人 herdr 配置与迁移笔记。配置由 tmux/.tmux.conf 映射而来。

• config.toml — 真实配置，经 script/herdr-init.sh 软链到 ~/.config/herdr/config.toml
• 校验：herdr config check
• 热重载：prefix+shift+r（本配置改为 prefix+r）或 herdr server reload-config
• 默认值参考：herdr --default-config
• 官方速查：https://herdr.dev/docs/concepts/ ，给 agent 看的：herdr --skill

概念对照

tmux	herdr	说明
session	workspace	herdr 的 workspace 对应“一个项目/任务”，侧栏按 workspace 汇总 agent 状态
（无对应）	session	herdr 的 named session 是独立的 server 命名空间（herdr session attach work），跟 tmux 的 session 不是一回事
window	tab
pane	pane	只能向右（right）或向下（down）切
prefix mode	prefix mode (ctrl+b)	相同；另有 terminal mode / navigate mode
status bar + 脚本	sidebar	鼠标可点、可拖分隔条、右键菜单
（无对应）	agent	herdr 识别 pane 里的 coding agent，状态 working/blocked/done/idle/unknown
tmux-resurrect	session.json + [experimental] pane_history	布局自动持久化，agent 原生会话恢复需要装 integration
tpm 插件	无插件系统	fzf 类能力内建（prefix+w workspace picker、prefix+g goto）；自定义动作用 [[keys.command]]
tmux over ssh	herdr --remote <ssh-target>	远端跑 server，本地 attach

和 tmux 的主要差异

1. 鼠标优先。所有交互都能用鼠标完成；键位是可选层。prefix+? 可实时列出当前所有有效绑定。
2. agent 感知。侧栏能看到每个 pane 里的 agent 状态，blocked（等你审批/回答）会被顶到前面。tmux 只能靠 pane 标题自己写。
3. CLI + 本地 socket API。herdr pane split/run/read/wait-output、herdr agent prompt/wait 这类命令可以从脚本或 agent 内部驱动布局和读输出，tmux 的 send-keys 做不到等待与状态判定。
4. 配置是单个 TOML，没有插件系统，也没有 run-shell 状态栏脚本；但支持 [[keys.command]] 自定义命令（type = "shell" / "pane" / "popup"，可指定宽高百分比），基本能覆盖原来用插件/脚本做的事。
5. 直接快捷键。除 prefix+... 外还支持 ctrl+alt+... 这类直通键位（适合想摆脱 prefix 的用法）。反过来，被 OS 或外层终端占用的组合 herdr 收不到，表现为“绑了没反应”。
6. 没有 escape-time / terminal-overrides / 真彩色开关。那些是 tmux 作为终端适配层才需要的，herdr 自己处理能力协商。通知走 [ui.toast] delivery，剪贴板走 [ui] copy_on_select。
7. 不支持嵌套启动（experimental.allow_nested = false）：herdr pane 里再跑 herdr 会被拒绝。tmux 里 tmux 是能套的。
8. [remote] manage_ssh_config 默认开启：herdr --remote 会生成一份私有 ssh config，先 include 你的 ~/.ssh/config，再补 ServerAliveInterval/ServerAliveCountMax 兜底，并用私有 control socket 复用连接。所以 ~/.ssh/config 里已有的 keepalive 仍然优先，我们的 Include ~/.ssh/config.d/* 也照常生效。

切换时的注意事项

• 分屏按分隔线的形状记：| 是竖线 → 切成左右；- 是横线 → 切成上下。herdr 就是按形状命名的（split_vertical = 竖线 = 向右切，split_horizontal = 横线 = 向下切），而 tmux 的 splitw -v/-h 按“排列方向”命名，两者相反：tmux splitw -v（上下堆叠）对应 herdr split_horizontal，tmux splitw -h（左右并排）对应 split_vertical。本配置按形状对齐（- 上下、| 左右）。
• herdr 裸跑会 attach；herdr server 是前台 headless server。别为了“看看帮助”敲 herdr server——它不返回，会把调用它的地方永久挂住（踩过一次：pi 的 bash 工具卡了 46 分钟）。要看帮助用 herdr --help、herdr <group>（如 herdr pane）；停 server 用 herdr server stop。
• prefix 都是 ctrl+b，两套配置不冲突，但同时开难免按错。切过去之前建议先退掉 tmux，避免双层状态栏/双层 prefix。
• 没有 -c '#{pane_current_path}' 这个开关：新建 pane/tab 的目录策略在 [terminal] new_cwd（follow / home / current / 固定路径），本配置是 follow。
• resize 步长不可配。tmux 那边是固定 10 格；herdr 直接绑定（本配置 prefix+shift+hjkl）用默认步长，或 prefix+r 进 resize mode 再动。
• mouse on/off 没有运行时快捷键：由 [ui] mouse_capture 决定，运行时去 prefix+s 设置面板改。用 copy_on_select = false 可以在拖选后保留选区，等 Ctrl+C 再复制。
• 复制模式：mode-keys vi 在 herdr 没有等价配置。本配置给 copy_mode 绑了 prefix+[（herdr 0.8.2 支持该校验通过，但未写进 --default-config），复制模式的内部键位不可配；平时直接鼠标拖选即可。想把 scrollback 丢进 $EDITOR 用 prefix+e。
• 中文/IME：如果你在 pane 里用 pi/claude/codex 这类自绘光标的 TUI 遇到输入法候选框错位，可试开 [experimental] reveal_hidden_cursor_for_cjk_ime = true（可用 cjk_ime_agents 限定只对某些 agent 生效）。默认关闭。
• 别再跑 tpm：script/tmux-init.sh 会克隆 tpm 并装插件，那是 tmux 的；herdr 不需要。两套可以并存，但别指望插件搬到 herdr。
• 升级：herdr update（stable 通道）；0.8.2 → 0.9.0 已经可用。用包管理器装的则走包管理器。

迁移状态

• herdr/config.toml（tmux 键位/UI 行为映射，herdr config check 通过）
• script/herdr-init.sh（软链 + 备份 + 幂等 + 校验）
• 装 agent integration（herdr integration install claude 等），才有原生会话恢复与状态上报
• 需要时启用 reveal_hidden_cursor_for_cjk_ime