一天一个开源项目（第210篇）：herdr - AI 编程 Agent 的运行时底座

引言

"The runtime your coding agents live on."

这是"一天一个开源项目"系列的第 210 篇文章。今天带你了解的项目是 herdr。

你有没有遇到过这种情况：让 Claude Code 跑一个大任务，合上笔记本盖子，回来发现整个会话断掉了，任务不知道执行到哪一步。或者多个 Agent 同时运行，不知道哪个卡住了，要挨个终端去翻。

这是 AI 编程工作流的一个系统性问题：现有的 Agent 工具很强大，但缺少一个持久化的"运行时底座"------一个能让 Agent 会话存活、能追踪 Agent 状态、能让 Agent 之间协调的基础层。

herdr 就是这个底座。

一个 Rust 写的单一二进制文件，没有 Electron，没有多余依赖。它像一个专为 AI Agent 设计的终端复用器：会话永不丢失，每个 Agent 的状态实时可见，Agent 之间可以通过 Socket API 互相协调。

34.5k Stars，659K 安装量，909 个社区插件，Apache 2.0，YC 2026 支持。

你将学到什么

herdr 的两种 Agent 状态检测机制（生命周期钩子 vs 屏幕快照扫描）
working / blocked / idle 三态模型的设计意图
Socket API 的完整控制面：从拆分面板到跨 Agent 等待
agent.prompt + agent.wait 原子操作如何避免竞态
Plugin 系统的本地可执行文件 + manifest 设计
环境变量注入机制

前置知识

用过终端复用器（tmux 或类似工具）
对 AI 编程 Agent（Claude Code、Codex 等）有基本了解
了解 Unix Socket / 进程间通信的基本概念（可选）

项目背景

项目简介

herdr 定位自己为 "AI 编程 Agent 的运行时（runtime）"------不是一个新的 Agent，而是 Agent 运行在上面的基础设施。

它的核心主张："nothing else about your setup changes"。你的 Claude Code、Codex、Cursor 该怎么用还怎么用，herdr 只是在下面提供持久化的环境，加上 Agent 感知能力和协调 API。

从技术角度看，herdr 是一个"Agent 原生终端复用器"：

像 tmux 一样管理终端会话、面板、窗口
额外增加了 Agent 状态感知（知道哪个 Agent 在干什么）
提供 Socket API 让 Agent 互相通信和协调
插件系统支持扩展自定义工作流

作者/团队介绍

团队: herdrdev
官网 : herdr.dev
背书: YC 2026 支持
许可证: Apache 2.0

项目数据

⭐ GitHub Stars: 34,500+
🍴 Forks: 2,500+
📄 License: Apache 2.0
💻 主要语言: Rust（单一二进制）
🌐 官网: herdr.dev
📦 安装: curl -fsSL https://herdr.dev/install.sh | sh
🔌 社区插件: 909 个
📥 安装量: 659K

主要功能

核心作用

herdr 在你的开发环境和 AI Agent 之间建立了一个持久化的调度层：

javascript 复制代码

┌─────────────────────────────────────────────────────┐
│                  herdr server（后台常驻）              │
│                                                     │
│  Workspace 1                                        │
│    Tab: dev                                         │
│      ┌────────────────┬────────────────┐            │
│      │ Pane w1:p1     │ Pane w1:p2     │            │
│      │ Claude Code    │ Codex          │            │
│      │ 状态: working  │ 状态: blocked  │            │
│      └────────────────┴────────────────┘            │
│                                                     │
│  Socket API: ~/.config/herdr/herdr.sock             │
│  环境变量注入: HERDR_SOCKET_PATH / HERDR_PANE_ID    │
└─────────────────────────────────────────────────────┘
         ↑
    Agent 通过 CLI 或 Socket 直接控制这个层

使用场景

长任务持久化
- 让 Claude Code 跑一个多小时的重构任务，合上笔记本，第二天早上 reattach，任务还在。不再依赖终端窗口保持打开。
多 Agent 状态监控
- 5 个 Agent 并行工作，herdr 的状态栏实时显示哪个在 working、哪个被 blocked（等待用户输入）、哪个 idle（空闲）。不用挨个切换终端去检查。
Agent 自动化协调
- Agent A 完成任务后，通过 Socket API 通知 Agent B 开始下一步。或者让一个 orchestrator Agent 等待 worker Agent 的 done 状态再汇总结果。
远程开发机管理
- SSH 连接到远程开发机，reattach 到正在运行的 Agent 会话，就像从未断开过。
团队工作流标准化
- 通过 herdr 的 Layout API 声明式定义工作区布局，一键复现整个多 Agent 开发环境。

快速开始

bash 复制代码

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

# macOS (Homebrew)
brew install herdr

# 启动服务器
herdr start

# 在 herdr 里打开 Claude Code
herdr run "claude"

# 查看所有 Agent 状态
herdr agent list

# 拆分面板，在新面板里运行 Codex
herdr pane split w1:p1 --direction right
herdr pane run w1:p2 "codex"

核心特性

1. 会话持久化

herdr 是一个后台常驻服务器，不依赖任何终端窗口保持打开。支持的持久化场景：

合盖 / 睡眠后重新打开
网络断开重连
SSH 断线后重新 attach
机器重启后会话恢复（session.snapshot 机制）

bash 复制代码

# 从任意终端重新接入
herdr attach
herdr attach --session my-project

# 直接接入某个 Agent
herdr agent attach claude-code-main
herdr agent attach claude-code-main --takeover  # 抢占输入控制权

2. Agent 三态状态追踪

每个面板的 Agent 状态始终处于三个状态之一：

状态	含义
`working`	Agent 正在执行任务
`blocked`	Agent 等待用户批准/输入（权限请求、问题确认等）
`idle`	Agent 空闲，等待下一个任务

状态向上传播：一个 blocked 的 Agent 会让所属的面板、标签页、工作区都显示 blocked。

两种检测机制：

生命周期钩子：Agent 通过插件主动上报状态（权威来源，优先级最高）
屏幕快照扫描：herdr 截取终端底部缓冲区，对照 TOML 规则库判断状态（fallback 方案）

blocked 状态故意设置得严格------只有屏幕上出现已知的审批/权限 UI 时才触发。未知的提示界面先显示为 idle，避免误报。

bash 复制代码

# 诊断某个面板的状态检测结果
herdr agent explain w1:p1

3. Socket API：完整控制面

herdr 通过 Unix domain socket（Windows 上是 named pipe）暴露 JSON RPC API。协议是换行分隔的 JSON：

json 复制代码

// 请求
{"id":"req_1","method":"ping","params":{}}
// 响应
{"id":"req_1","result":{"type":"pone"}}

Socket 路径：

默认：~/.config/herdr/herdr.sock
命名会话：~/.config/herdr/sessions/<name>/herdr.sock

herdr 自动向所有受管面板注入环境变量：

bash 复制代码

$HERDR_SOCKET_PATH     # socket 地址，Agent 直接用这个连接
$HERDR_ENV=1           # 标记当前在 herdr 环境中
$HERDR_WORKSPACE_ID    # 当前工作区 ID
$HERDR_TAB_ID          # 当前标签页 ID
$HERDR_PANE_ID         # 当前面板 ID（Agent 知道自己在哪里）

Agent 不需要任何配置就能发现 herdr------直接读环境变量即可。

4. 跨 Agent 协调：prompt + wait 原子操作

这是 herdr 最有价值的 API 能力之一。传统方案是"发送文本 + 等待输出"，存在竞态问题：发送和等待之间如果 Agent 状态已经变化，结果不确定。

herdr 的解法是原子化的 agent.prompt：

json 复制代码

{
  "method": "agent.prompt",
  "params": {
    "pane_id": "w1:p1",
    "text": "分析 src/ 目录并生成测试用例",
    "wait": {
      "until": "done",
      "timeout_ms": 300000
    }
  }
}

agent.prompt + wait 在一个请求里完成，避免了"发送"和"等待"之间的竞态。如果 Agent 已经处于 blocked 状态，调用直接返回 agent_blocked 错误，不会盲目发送输入。

bash 复制代码

# 命令行等价操作
herdr agent wait w1:p1 --until done
herdr agent wait w1:p1 --until blocked --timeout 60000

5. 声明式布局 API

通过 layout.apply 声明整个多 Agent 工作区结构：

json 复制代码

{
  "method": "layout.apply",
  "params": {
    "workspace_id": "w1",
    "tab_label": "dev",
    "root": {
      "type": "split",
      "direction": "right",
      "ratio": 0.65,
      "first": {"type": "pane", "label": "claude", "cwd": "/repo"},
      "second": {
        "type": "split",
        "direction": "bottom",
        "ratio": 0.5,
        "first": {"type": "pane", "label": "codex", "cwd": "/repo"},
        "second": {"type": "pane", "label": "tests", "command": ["sh", "-c", "just test"]}
      }
    }
  }
}

一个 JSON 定义整个布局，可以版本控制、团队共享，一键复现。

6. Plugin 系统

插件是"本地可执行文件 + manifest"：

manifest actions：声明插件可以执行的动作
event hooks：订阅 herdr 事件（pane.agent_status_changed、pane.output_matched 等）
plugin.pane.open：插件可以打开自己的 UI 面板（overlay / popup / split / tab / zoomed 模式）

插件通过 GitHub 仓库分享，社区目前已有 909 个。

项目详细剖析

为什么是 Rust + 单一二进制

herdr 有意选择不用 Electron：

复制代码

传统桌面 AI 工具（Electron）：
  Node.js runtime + V8 + Chromium + 几十 MB 依赖
  ↓
启动慢、内存大、无法在纯终端环境运行

herdr（Rust 单一二进制）：
  一个可执行文件，零外部依赖
  ↓
启动快（毫秒级）、内存占用小、SSH 环境里完全可用

对于"始终后台运行的服务器"这个定位，Rust 单一二进制是正确的技术选择。

屏幕快照检测的工作原理

对于没有原生钩子的 Agent，herdr 用屏幕扫描来检测状态：

markdown 复制代码

1. 截取面板的"底部缓冲区快照"（不是滚动视口）
   ↓
2. 对照 TOML 规则库进行匹配
   每个 Agent 有自己的规则文件（built-in + 远程更新 + 本地覆盖）
   ↓
3. 判断状态：
   - 匹配到已知的 blocked UI → blocked
   - 匹配到已知的 working 模式 → working
   - 其他情况 → idle（安全 fallback）
   ↓
4. 状态结果上报给 herdr server

规则文件可以远程更新（不需要重启），本地 ~/.config/herdr/agent-detection/<agent>.toml 始终优先。

事件订阅系统

除了主动查询，herdr 支持事件订阅：

json 复制代码

{
  "method": "events.subscribe",
  "params": {
    "subscriptions": [
      {
        "type": "pane.agent_status_changed",
        "pane_id": "w1:p1",
        "agent_status": "blocked"
      }
    ]
  }
}

可订阅的事件类型：

pane.created / updated / closed / focused / moved / exited
pane.agent_detected：检测到 Agent 进入面板
pane.agent_status_changed：Agent 状态变化
pane.output_matched：面板输出匹配特定模式
pane.scroll_changed：滚动位置变化

这让 "orchestrator Agent" 模式成为可能：一个 Agent 监听其他 Agent 的状态事件，在适当时机发送指令或汇总结果。

支持的 Agent 列表

herdr 原生支持 21 种 AI 编程工具：

类别	工具
主流	Claude Code、Codex、GitHub Copilot CLI、Cursor Agent CLI、Grok CLI
新兴	OpenCode、Kilo Code CLI、Amp、Qwen Code、Kimi Code CLI
专用	Pi、OMP、Devin CLI、MastraCode
测试中	Gemini CLI、Cline

项目地址与资源

官方资源

🌟 GitHub : github.com/herdrdev/he...
📚 文档 : herdr.dev/docs
🌐 官网 : herdr.dev
📦 安装 : curl -fsSL https://herdr.dev/install.sh | sh
🔌 插件: 社区 909 个插件，通过 herdr 内置市场浏览

总结与展望

核心要点回顾

定位清晰：不是新 Agent，而是让现有 Agent 工作得更好的运行时底座
Rust 单一二进制：后台常驻、启动快、零依赖，适合"始终运行"的服务器定位
三态检测 ：working / blocked / idle 精确反映 Agent 真实状态，blocked 故意严格以避免误报
原子化 prompt + wait：解决了多 Agent 协调中的经典竞态问题
声明式布局：JSON 定义整个多 Agent 工作区，可版本控制、可团队共享

适用人群

同时跑多个 AI 编程 Agent 的开发者：herdr 的状态面板让你一眼看清所有 Agent 在做什么
需要长时间运行 Agent 任务的工程师：持久化会话，合盖不中断
想构建 Agent 自动化编排的团队：Socket API + 事件订阅提供了完整的编排原语
远程开发机用户：SSH 断线后 reattach，体验和本地一样

一句话评价

herdr 回答的问题很简单：当 AI Agent 成为日常开发的一部分，你需要一个能装得下它们的地方------就像服务器需要一个操作系统一样。

欢迎访问 PrimeSkills ------ 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。

更多实用知识和有趣产品，欢迎访问我的个人主页

一天一个开源项目（第210篇）：herdr - AI 编程 Agent 的运行时底座

引言

你将学到什么

前置知识

项目背景

项目简介

作者/团队介绍

项目数据

主要功能

核心作用

使用场景

快速开始

核心特性

项目详细剖析

为什么是 Rust + 单一二进制

屏幕快照检测的工作原理

事件订阅系统

支持的 Agent 列表

项目地址与资源

官方资源

相关项目

总结与展望

核心要点回顾

适用人群

一句话评价