herdr — 终端 AI Agent 多路复用器深度调研

调研时间：2026-06-07 项目地址：https://github.com/ogulcancelik/herdr 官网：https://herdr.dev 版本：v0.6.8 许可证：AGPL-3.0（有商业许可选项）

一、项目概述

herdr 是一个用 Rust 编写的终端多路复用器（类似 tmux），专为同时管理多个 AI 编码代理而设计。它提供工作区、标签页、面板的组织结构，同时内置 AI agent 状态感知能力——侧边栏实时显示每个 agent 的工作状态（blocked/working/done/idle）。

核心卖点：

像 tmux 一样的终端复用（工作区、标签、面板、会话持久化）
内置 AI agent 状态感知（自动检测 agent 运行状态）
支持 15+ 主流 AI 编码代理（Claude Code、Codex、Copilot CLI、Amp 等）
Agent 可通过 Socket API 反向控制 herdr
鼠标原生支持（点击、拖拽、分割面板）
单个 Rust 二进制，无依赖

一句话定位：tmux + AI agent 状态监控 = herdr

二、技术架构

2.1 技术栈

维度	技术选型
语言	Rust (2021 edition)
TUI 框架	ratatui + crossterm
PTY 管理	portable-pty
异步运行时	tokio (multi-thread)
IPC	Unix domain socket (interprocess)
序列化	serde/serde_json/toml
日志	tracing
构建工具	Cargo + justfile + Nix flake
平台	Linux, macOS, Windows (beta)

2.2 架构模式

Client-Server 架构：

Server 进程在后台运行，管理所有 PTY 面板
Client 进程负责终端渲染和用户输入
通过 Unix socket 通信
Detach 时只关闭 Client，Server 和进程继续运行

Elm-style 状态管理：

AppState 是纯数据，可脱离 PTY/async 独立测试
compute_view() 处理几何和状态变更
render() 只读取 &AppState 并绘制，不修改状态

2.3 源码结构

src/
├── main.rs              # 入口点 (28KB)
├── app/                 # 应用状态/生命周期
├── cli.rs + cli/        # 命令行解析
├── client/              # IPC 客户端
├── server/              # IPC 服务端
├── pane.rs (117KB)      # 面板管理（最大模块）
├── update.rs (116KB)    # Elm 架构状态更新
├── ui.rs + ui/          # TUI 渲染
├── layout.rs            # 面板布局
├── session.rs           # 会话管理
├── workspace.rs         # 工作区管理
├── worktree.rs          # Git worktree
├── pty/                 # PTY 创建和 I/O
├── terminal/            # 终端模拟
├── protocol/            # 通信协议定义
├── detect/              # Agent 状态检测逻辑
├── input/               # 键盘/鼠标输入
├── config.rs + config/  # TOML 配置
├── integration/         # 终端集成
├── remote/              # 远程会话
├── agent_resume.rs      # Agent 会话恢复
└── sound.rs             # 音频通知

三、安装方式

3.1 官方安装脚本（推荐）

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

3.2 Homebrew (macOS/Linux)

brew install herdr

3.3 mise

mise use -g herdr

3.4 直接下载二进制

从 GitHub Releases 下载对应平台二进制：

herdr-linux-x86_64
herdr-linux-aarch64
herdr-macos-x86_64
herdr-macos-aarch64

# 示例：Linux x86_64
wget https://github.com/ogulcancelik/herdr/releases/download/v0.6.8/herdr-linux-x86_64
chmod +x herdr-linux-x86_64
sudo mv herdr-linux-x86_64 /usr/local/bin/herdr

3.5 从源码编译

git clone https://github.com/ogulcancelik/herdr
cd herdr
cargo build --release
./target/release/herdr

3.6 更新

herdr update

可选择 preview 频道获取最新预览版：

herdr channel set preview   # 切换到预览频道
herdr channel set stable    # 切回稳定频道

四、核心功能详解

4.1 工作区/标签/面板

herdr 的组织层次：

Session (会话)
└── Workspace (工作区，通常对应一个 git repo)
    └── Tab (标签页)
        └── Pane (面板，真实终端进程)

工作区：项目级容器，按 git repo 或文件夹组织
标签页：工作区内的分组，Socket API 和 CLI 一等公民
面板：真实终端进程，不是 agent 输出的重新渲染

4.2 Agent 状态感知

侧边栏实时显示每个 agent 的状态：

状态	图标	含义
blocked	🔴	Agent 需要用户输入或审批
working	🟡	Agent 正在工作
done	🔵	工作完成，用户尚未查看
idle	🟢	完成且已查看

检测机制（三层信号模型）：

进程名匹配：检测前台进程名（如 claude, codex）
终端输出启发式：分析终端底部缓冲区内容判断状态
集成事件：官方集成通过 Socket API 主动上报状态

零配置即可工作，无需 hook 或额外设置。

4.3 支持的 AI Agent

Agent	idle/done	working	blocked
Claude Code	✓	✓	✓
Codex (OpenAI)	✓	✓	✓
Amp	✓	✓	✓
GitHub Copilot CLI	✓	✓	✓
Grok CLI	✓	✓	✓
OpenCode	✓	✓	✓
Pi	✓	✓	partial
Droid (Factory AI)	✓	✓	✓
Hermes Agent	✓	✓	✓
Kilo Code CLI	✓	✓	✓
Cursor Agent	✓	✓	✓
Kimi Code CLI	✓	✓	✓
QoderCLI	✓	✓	✓
Kiro CLI	✓	✓	—
Antigravity CLI	✓	✓	✓

4.4 会话持久化

Detach/Reattach：prefix+q detach，再运行 herdr reattach
进程存活：detach 后所有面板进程继续运行
会话恢复：重启后可恢复面板，支持最近屏幕历史
命名会话：herdr session attach work 管理独立命名空间

4.5 远程连接

# SSH 到远程后直接运行
ssh you@server
herdr
 
# 或本地直接 attach 远程
herdr --remote workbox
herdr --remote ssh://you@server:2222

4.6 Socket API

本地 Unix socket 允许 agent 反向控制 herdr：

# Agent 可以：
# - 创建工作区/标签/面板
# - 读取面板输出
# - 上报自己的状态
# - 等待状态变化
# - 发送按键到面板

协议格式：换行分隔的 JSON (NDJSON)。

关键 API 方法：

workspace.create / workspace.list
tab.create / tab.list
pane.create / pane.read / pane.send_keys
pane.report_agent — agent 主动上报状态
pane.report_agent_session — 上报会话 ID 用于恢复
events.subscribe — 订阅状态变化事件

五、使用指南

5.1 快速开始

# 1. 在项目目录启动 herdr
cd ~/my-project
herdr
 
# 2. 创建新工作区
# prefix + Shift+N
 
# 3. 在面板中启动 AI agent
claude   # 或 codex, amp 等
 
# 4. 分割面板运行更多 agent
# prefix + v  (垂直分割)
# prefix + -  (水平分割)
 
# 5. 切换面板
# prefix + h/j/k/l
 
# 6. Detach（agent 继续运行）
# prefix + q
 
# 7. 重新连接
herdr

5.2 默认快捷键

前缀键：Ctrl+B（与 tmux 相同）。完整快捷键见附录 A，此处列出高频常用键：

快捷键	功能
`prefix + c`	新建标签页
`prefix + n` / `prefix + p`	下一个/上一个标签页
`prefix + 1..9`	切换到第 N 个标签页
`prefix + w`	工作区选择器
`prefix + Shift+N`	新建工作区
`prefix + h/j/k/l`	切换面板焦点（左/下/上/右）
`prefix + v` / `prefix + -`	垂直/水平分割面板
`prefix + x`	关闭当前面板
`prefix + z`	面板全屏/还原
`prefix + r`	进入调整大小模式
`prefix + b`	切换侧边栏
`prefix + q`	Detach（agent 继续运行）
`prefix + [`	进入复制模式
`prefix + ?`	查看帮助

5.3 安装官方集成

官方集成提供更精确的状态检测和会话恢复：

herdr integration install claude    # Claude Code
herdr integration install codex     # OpenAI Codex
herdr integration install copilot   # GitHub Copilot CLI
herdr integration install opencode  # OpenCode
herdr integration install pi        # Pi
herdr integration install hermes    # Hermes Agent
herdr integration install qodercli  # QoderCLI

5.4 配置文件

配置路径：~/.config/herdr/config.toml

# 打印完整默认配置
herdr --default-config

常用配置项：

# 主题（18 种内置主题）
[theme]
name = "catppuccin"   # 可选：tokyo-night, gruvbox, solarized 等
 
# 侧边栏
[sidebar]
enabled = true
position = "left"     # left/right
 
# 通知
[notifications]
sound = true
toast = true
 
# 快捷键自定义
[[keybindings]]
key = "ctrl+b"
action = "prefix"

5.5 命名会话管理

herdr session attach work     # 创建/连接命名会话 "work"
herdr session list            # 列出所有会话
herdr session stop work       # 停止会话
herdr server stop             # 停止默认会话

5.6 复制模式

鼠标拖选：直接在面板内拖选文字
双击：选中单词/token
键盘模式：prefix + [ 进入，h/j/k/l 移动，v 开始选择，y 复制，q 退出

六、典型使用场景

6.1 多 Agent 并行开发

同时运行多个 Claude Code 实例处理不同任务：

┌─────────────────────┬──────────────────────┐
│ Claude Code         │ Claude Code          │
│ (修复 Bug #123)     │ (实现新功能)          │
│ 🟡 working         │ 🔴 blocked           │
├─────────────────────┼──────────────────────┤
│ Codex              │ Terminal              │
│ (写测试)            │ (手动验证)            │
│ 🟢 idle            │                      │
└─────────────────────┴──────────────────────┘

侧边栏一眼看到哪个 agent 需要你的注意（blocked 状态）。

6.2 远程开发服务器

# 连接远程服务器，启动 herdr
herdr --remote dev-server
 
# 在远程运行多个 agent
# Detach 后 agent 继续跑
# 随时重新连接查看进度

6.3 Agent 编排（高级）

Agent 可以通过 Socket API 自动编排：

# Claude Code 可以自己创建新面板运行测试
herdr pane create --workspace main --command "npm test"
 
# 读取其他面板输出
herdr pane read --pane-id <id> --source recent
 
# 等待其他 agent 完成
herdr pane wait --pane-id <id> --state done

七、与同类工具对比

7.1 vs tmux

维度	tmux	herdr
成熟度	20+ 年历史，极其稳定	2.5 个月，快速迭代中
Agent 感知	无	内置，自动检测
鼠标支持	有限	原生支持
学习曲线	高	中（tmux 用户秒上手）
生态/插件	极丰富	无
资源占用	极低	较高（15-25% 单核）
CJK 支持	成熟	有已知问题

7.2 vs GUI Agent 管理器

维度	GUI 管理器	herdr
Agent 状态	✓	✓
终端原生	✗（要离开终端）	✓
会话持久化	✗	✓
远程支持	有限	SSH 原生
看到 Agent 原始终端	✗（重新渲染）	✓

7.3 vs zellij

维度	zellij	herdr
语言	Rust	Rust
定位	通用终端复用器	AI Agent 专用
Agent 感知	无	内置
插件系统	WASM 插件	Socket API
稳定性	较高	中等

八、实际体验评价

8.1 社区评价（来源：HN、Reddit、GitHub Issues）

正面评价：

“我用 herdr 管理多个 agent 的主力工具” — HN 用户
“刚测试了 herdr，真的很喜欢！” — rmux 作者
2.5 个月 4,849 stars，增长迅猛

负面反馈：

“面板管理不够好，不能移动或重排面板” — 用户 cultofmetatron
“Agent 运行时 herdr 占用 15-25% CPU (M3 Max)” — Issue #399
多个 Issue 反馈 agent 状态检测不准确（卡在 working、误报 idle）
CJK 文本显示有乱码问题
Socket API 无鉴权（安全隐患）

8.2 已知问题

问题	严重程度	状态
CPU 占用高（agent 活跃时 15-25%）	中高	已知
Agent 状态检测不准	中	持续改进
面板不能移动/重排	中	功能缺失
CJK 文本乱码	中	已知
韩文 IME 问题	中	已知
WSL 剪贴板不工作	低	已知
Socket API 无鉴权	低	已知
Kitty 图形在嵌套 TUI 中不渲染	低	已知

8.3 维护情况

维护者：ogulcancelik（单人维护）
响应速度：当天响应 issue，发版节奏快
提交频率：每天多次提交
版本迭代：从 v0.4.x 快速到 v0.6.x，30 个 tag
社区：18 个 open issues，有活跃讨论

九、适用场景建议

不推荐使用

只跑单个 agent（直接用终端就行）
对终端复用器稳定性要求极高的生产环境
CJK 重度用户（中文显示有已知问题）
对资源占用敏感的场景

替代方案

只需终端复用 → tmux / zellij
需要 GUI → 各 agent 官方 GUI 客户端
只需简单多开 → 多个终端标签

十、总结

herdr 填补了”终端内同时监控多个 AI 编码助手”这个真实需求空白。它的核心价值在于 agent 状态感知——侧边栏实时显示每个 agent 在干什么，让你高效管理并行 agent 工作流。

当前状态：可用但粗糙，适合尝鲜者，快速迭代中。

未来潜力：如果 CPU 占用和状态检测准确性能解决，有望成为多 agent 开发的标配工具。

附录 A：快捷键完整速查（v0.6.8）

前缀键默认 Ctrl+B，所有 prefix+* 需先按前缀键再按后续键。可在 ~/.config/herdr/config.toml 的 [keys] 段自定义所有绑定。

全局 / 系统

快捷键	功能
`prefix + ?`	打开帮助/快捷键列表
`prefix + s`	打开设置
`prefix + q`	Detach（断开客户端，进程继续运行）
`prefix + Shift+R`	重载配置文件（热更新，无需重启）
`prefix + o`	打开通知目标（跳转到通知来源面板）

工作区（Workspace）

快捷键	功能
`prefix + w`	工作区选择器（导航弹出）
`prefix + Shift+N`	新建工作区
`prefix + Shift+W`	重命名当前工作区
`prefix + Shift+D`	关闭当前工作区
`prefix + Shift+G`	新建 Git Worktree（并创建对应工作区）
`prefix + g`	会话/全局跳转导航

未默认绑定（可在配置中设置）：

previous_workspace / next_workspace — 切换上/下一个工作区

switch_workspace — 按序号直接跳转，建议配 "prefix+shift+1..9"

open_worktree / remove_worktree — 打开/移除 worktree

标签页（Tab）

快捷键	功能
`prefix + c`	新建标签页（会弹出命名输入）
`prefix + n`	切换到下一个标签页
`prefix + p`	切换到上一个标签页
`prefix + 1..9`	直接切换到第 N 个标签页
`prefix + Shift+T`	重命名当前标签页
`prefix + Shift+X`	关闭当前标签页

面板（Pane）

快捷键	功能
`prefix + v`	垂直分割面板（右侧新建）
`prefix + -`	水平分割面板（下方新建）
`prefix + x`	关闭当前面板
`prefix + z`	当前面板全屏/取消全屏（zoom）
`prefix + h`	焦点移到左侧面板
`prefix + j`	焦点移到下方面板
`prefix + k`	焦点移到上方面板
`prefix + l`	焦点移到右侧面板
`prefix + Tab`	循环切换到下一个面板
`prefix + Shift+Tab`	循环切换到上一个面板
`prefix + Shift+P`	重命名当前面板

未默认绑定（可在配置中设置）：

last_pane — 快速切换到上一个焦点面板，建议配 "prefix+tab"

focus_agent — 按序号跳转到第 N 个 Agent 面板，建议配 "prefix+alt+1..9"

调整大小模式（Resize Mode）

按 prefix + r 进入，再用以下键调整，Esc 或 Enter 退出：

键	功能
`h`	向左缩小（扩大左邻）
`j`	向下扩大
`k`	向上扩大
`l`	向右扩大

复制模式（Copy Mode）

按 prefix + [ 进入，或直接鼠标拖选：

键	功能
`h / j / k / l`	移动光标
`v`	开始选择
`y`	复制选中内容
`q`	退出复制模式
鼠标拖选	直接选中
双击	选中单词/token

prefix + e — 在外部编辑器中打开滚动缓冲区（$EDITOR）

侧边栏 / AI Agent 状态面板

快捷键	功能
`prefix + b`	切换侧边栏显示/隐藏

侧边栏状态图标含义：

图标	状态	含义
🔴	blocked	Agent 等待用户输入或审批
🟡	working	Agent 正在运行中
🔵	done	任务完成，用户未查看
🟢	idle	完成且已查看

导航弹出层（Navigate Mode）

prefix + w（工作区选择器）或 prefix + g（全局跳转）弹出后：

键	功能
`↑ / ↓`	在工作区列表上下移动
`h` 或 `←`	聚焦左侧面板
`j`	聚焦下方面板
`k`	聚焦上方面板
`l` 或 `→`	聚焦右侧面板
`1..9`	直接跳转到对应项
`Enter`	确认选择
`Esc`	取消/关闭弹出层

自定义命令绑定示例

在 ~/.config/herdr/config.toml 中添加，可将任意 shell 命令绑定到快捷键：

# type = "pane"  → 在临时面板中运行，命令退出后自动关闭面板
# type = "shell" → 在后台静默运行，不打开面板
[[keys.command]]
key = "prefix+alt+g"
type = "pane"
command = "lazygit"

附录 B：CLI 命令速查

herdr                           # 启动/连接默认会话
herdr --default-config          # 打印默认配置
herdr update                    # 更新到最新版
herdr --version                 # 查看版本
 
# 会话管理
herdr session attach <name>     # 连接命名会话
herdr session list              # 列出会话
herdr session stop <name>       # 停止会话
herdr server stop               # 停止默认服务
 
# 远程
herdr --remote <host>           # 远程连接
 
# 集成
herdr integration install <name>  # 安装集成
herdr integration list            # 列出已安装集成
 
# 面板操作（CLI/Socket API）
herdr pane create --command <cmd>
herdr pane read --pane-id <id>
herdr pane send-keys --pane-id <id> --keys "ls\n"
herdr pane wait --pane-id <id> --state done
 
# 频道
herdr channel set preview       # 切换到预览频道
herdr channel set stable        # 切回稳定频道

Quartz 4

Explorer

herdr — 终端 AI Agent 多路复用器深度调研

herdr — 终端 AI Agent 多路复用器深度调研

一、项目概述

二、技术架构

2.1 技术栈

2.2 架构模式

2.3 源码结构

三、安装方式

3.1 官方安装脚本（推荐）

3.2 Homebrew (macOS/Linux)

3.3 mise

3.4 直接下载二进制

3.5 从源码编译

3.6 更新

四、核心功能详解

4.1 工作区/标签/面板

4.2 Agent 状态感知

4.3 支持的 AI Agent

4.4 会话持久化

4.5 远程连接

4.6 Socket API

五、使用指南

5.1 快速开始

5.2 默认快捷键

5.3 安装官方集成

5.4 配置文件

5.5 命名会话管理

5.6 复制模式

六、典型使用场景

6.1 多 Agent 并行开发

6.2 远程开发服务器

6.3 Agent 编排（高级）

七、与同类工具对比

7.1 vs tmux

7.2 vs GUI Agent 管理器

7.3 vs zellij

八、实际体验评价

8.1 社区评价（来源：HN、Reddit、GitHub Issues）

8.2 已知问题

8.3 维护情况

九、适用场景建议

推荐使用

不推荐使用

替代方案

十、总结

附录 A：快捷键完整速查（v0.6.8）

全局 / 系统

工作区（Workspace）

标签页（Tab）

面板（Pane）

调整大小模式（Resize Mode）

复制模式（Copy Mode）

侧边栏 / AI Agent 状态面板

导航弹出层（Navigate Mode）

自定义命令绑定示例

附录 B：CLI 命令速查

Graph View

Table of Contents

Backlinks