# 几个要先搞懂的概念

# 层级结构

从大到小，四层嵌套：

# Client / Server 分离

为什么 detach 不死？

• Server:后台进程，真正持有 agent。你关终端它还在。
• Client:终端 UI，只是"显示器 + 键盘",attach 到 server。
• Ctrl+B Q(detach)→ 客户端断开，server 继续。
• 再敲 herdr → reattach，界面原样恢复。

记住:agent 跑在 server 里，不是跑在你的终端里。这是 SSH 断线不丢 agent 的根本原因。

# 两层 Tab 不要混淆 (Ghostty 用户必读)

1
2
3

Ghostty(外层)        ← Cmd+1/2/3 切 Ghostty 原生 tab
  └─ Herdr(内层)     ← Ctrl+B 然后 1/2/3 切 Herdr 的 tab
       └─ Pane

Cmd+数字 是 Ghostty 的，Herdr 抢不到，所以 Herdr 用 prefix+ 数字。两层各管各的。

# 两端安装

# Mac 本机

1
2

curl -fsSL https://herdr.dev/install.sh | sh
herdr --version   # 验证

# Linux 服务器

SSH 上去后：

1
2

curl -fsSL https://herdr.dev/install.sh | sh
herdr --version

升级 (用官方脚本装的才适用):

1

herdr update

# 本地工作流

# 启动

1

herdr     # 启动 server + 打开 client(已存在则 attach)

# 干活

在 pane 里像平时一样启动 agent:

1
2
3

claude           # 启动 Claude Code
# 或多开
# Ctrl+B, V → 右切新 pane → 再敲 claude

侧边栏自动显示状态。

# 暂时离开

Ctrl+B 松开，再按 Q → detach,agent 继续跑。

# 回来

1

herdr     # reattach

# 彻底结束 (慎用，杀全部 agent)

1

herdr server stop

# 远程工作流 (SSH 场景)

这是你最大的收益区：SSH 断线不丢 agent。两种模式，按场景选。

# 模式 A:herdr --remote(Mac 日常用，推荐)

1

herdr --remote workbox

特点:

• Mac 当瘦客户端，SSH 连服务器，把服务器 Herdr 界面拉到本地
• agent 跑在服务器,但你在 Mac 上操作
• 图片粘贴能用(Herdr 把 Mac 剪贴板图片桥接到服务器)★裸 SSH 做不到
• 用 Mac 本地的快捷键配置

适合:你在 Mac 上日常连服务器干活，尤其要给 Claude 发截图时。

# 模式 B:先 SSH 再 herdr(tmux 式)

1
2

ssh workbox
herdr

特点:

• 整个 Herdr 在服务器上跑，终端只是显示器
• 图片粘贴不行
• 界面自适应窄屏

适合:手机/平板 SSH 连过去时、或临时简单连一下。

# 配置 SSH 别名

编辑 Mac 的 ~/.ssh/config:

1
2
3
4
5
6

Host workbox
  HostName server.example.com
  User you
  Port 2222
  ForwardAgent yes        # ★让服务器能借你 Mac 的 SSH 密钥做 git
  ServerAliveInterval 60  # 防 SSH 断线

之后直接：

1

herdr --remote workbox

# 典型的一天

1
2
3
4
5

上午  Mac: herdr --remote workbox
      → 连服务器,开 3 个 Claude 并行
开会  Ctrl+B Q → detach,服务器 agent 继续跑
下午  Mac: herdr --remote workbox → reattach,接着干
晚上  手机: ssh workbox → herdr → 窄屏看状态、做决策

# 日常操作速查

# Prefix 键 = Ctrl+B(先按，松开，再按动作键)

# 5 个必记

# Tab 操作

# Pane 操作

# Workspace 操作

# 鼠标操作

• 点击 pane / tab / workspace / agent → 切换
• 拖动分割边框 → 调整 pane 大小
• 选中文字 → 选中
• 右键 → 菜单
• 拖选 → 直接复制 (不用进 copy mode)

# 查看所有快捷键 (忘了随时查)

1

Ctrl+B → ?

# Agent 状态管理

# 五种状态

# done vs idle 的区别

• done:后台默默干完了，你没看过 → 提醒"有成果待领取"
• idle:你看过了 → 已知悉，待命

怎么算"看过":聚焦到那个 tab，或用 focus 命令 targeting 该 pane/agent。CLI 读取不算看过(防止 agent 自动操作误清状态)。

# 检测原理

Herdr 通过三方式识别 pane 里的 agent:

1. 前台进程
2. 屏幕特征 (screen manifests)—— 认审批框、加载态等
3. 可选集成插件 (装了更准)

零配置识别 Claude Code / Codex / OpenCode / Amp 等 20+ agent。

# 不要在 Herdr pane 里再开 tmux

会屏蔽 agent 状态检测(tmux 把内部输出吃掉)。要让状态功能生效，agent 必须直接跑在 Herdr pane 里。

# 多 Agent 并行

# 什么时候该多开

# 多开的正确姿势

• 用 git worktree 物理隔离:每个 agent 绑一个分支的工作目录，改的不是同一份代码
• agent 各干各的，不要让它们同时改同一份代码(merge 冲突地狱)
• 真并行(同时跑),不是串行流水线

# 创建 worktree 隔离的 workspace

1

herdr worktree create   # 把分支映射到独立 workspace

# 退出与恢复

日常退出永远用 Ctrl+B Q,只有确定不要 agent 才 herdr server stop。

# 配置与定制

# 配置文件位置

1

~/.config/herdr/config.toml

# 改 prefix 键

1
2

[keys]
prefix = "ctrl+a"   # 比如改成 Ctrl+A

# 无 prefix 直按键 (推荐配 Ctrl+Alt，跨终端安全)

1
2
3
4
5
6
7
8
9

[keys]
focus_pane_left = ["prefix+h", "ctrl+alt+h"]
focus_pane_down = ["prefix+j", "ctrl+alt+j"]
focus_pane_up = ["prefix+k", "ctrl+alt+k"]
focus_pane_right = ["prefix+l", "ctrl+alt+l"]
previous_tab = ["prefix+p", "ctrl+alt+["]
next_tab = ["prefix+n", "ctrl+alt+]"]
new_tab = ["prefix+c", "ctrl+alt+c"]
zoom = ["prefix+z", "ctrl+alt+z"]

官方推荐 Ctrl+Alt 家族：几乎不被任何终端/OS 占用。但要避开：

• Ctrl+Alt+方向键(Ghostty 占)
• Ctrl+Alt+T(Ubuntu 开终端)
• Ctrl+Alt+F1..F12(Linux 虚拟控制台)

# 关闭鼠标捕获

1
2

[ui]
mouse_capture = false

# 远程模式：用裸 ssh 不生成临时配置

1
2

[remote]
manage_ssh_config = false

# Named Session(一般不用，需要完全隔离时才用)

1
2
3
4

herdr session list
herdr session attach work
herdr session attach side-project
herdr session stop work

官方建议：先用 workspace，不够了再用 named session。