如果你平时习惯用 OpenCode 同时开好几个终端跑不同的 AI Agent 任务，大概率遇到过这种情况：切来切去找不到哪个窗口在跑、哪个已经跑完、哪个卡住了。今天要介绍的这个开源小工具 AgentPulse，就是专门为解决这个问题而生的------一个置顶悬浮的 AI Agent 运行状态中心。
项目地址：wuiyan/AgentPulse
它是什么
AgentPulse 是一个基于 Electron + React 的 Windows 桌面小工具，作用很单纯：实时监控本机正在运行的多个 OpenCode 会话状态，并以一个常驻置顶的小窗口形式展示出来，方便你随时掌握"现在有几个 Agent 在跑、跑到哪一步了、用的什么模型、花了多长时间"。
比较值得一提的是它的实现思路。市面上类似的监控工具很多会选择往目标程序里注入插件，或者搭一个 WebSocket bridge 来转发数据，但 AgentPulse 刻意避开了这两种做法：
- 不依赖 OpenCode 插件注入
- 不修改 OpenCode 配置文件
- 不使用 WebSocket bridge
它的做法是扫描 Windows 进程树和本机 TCP 监听端口，找到正在运行的 OpenCode Server，然后直接走 OpenCode SDK 提供的 HTTP/SSE 接口去获取会话状态------相当于"旁路观察"，不侵入目标进程本身。
界面长什么样
主界面按项目目录分组，展示当前正在执行或者已经追踪过的会话，可以看到任务标题、状态、耗时和使用的模型：
设置面板则提供了全局快捷键、会话定位失败后的启动策略，以及窗口置顶开关等选项：
整体窗口宽度只有 400px，走的是"桌面小工具"路线，不会占用太多屏幕空间，默认还会保持窗口始终置顶（也可以在设置里关掉）。
核心功能一览
- 自动扫描 Windows 进程树和本机 TCP 监听端口，发现可访问的 OpenCode Server
- 基于 OpenCode SDK v2 做健康检查、初始会话同步和 SSE 实时事件订阅
- 只展示"已经开始执行"的会话，避免历史会话把列表刷屏
- 按项目目录分组，支持项目组拖拽排序
- 点开会话时会尝试唤醒并置前对应的 VS Code、Windows Terminal 或 PowerShell 窗口
- 支持启动时扫描、手动扫描，以及通过 OpenCode shim 的启动/退出通知触发扫描
- Windows 安装包（NSIS）安装时可自动配置好 OpenCode shim，免去手动配置的麻烦
工作原理简述
整体的数据流大致是这样的：
yaml
Windows 进程表 + TCP 监听端口
|
v
OpenCode Server 发现
|
v
HTTP 健康检查
|
v
初始会话同步 + Global SSE 事件
|
v
SessionStore
|
v
Electron React 界面细节上有几个点比较值得关注:
程序只接受 loopback（本机回环）地址上的 HTTP 监听端口，并沿着监听进程的父进程链去查找对应的 OpenCode 进程和宿主窗口。进程快照采集用的是 systeminformation 库，其中 processes() 拿进程树，networkConnections()（内部通过 netstat -nao）拿 TCP 监听端口------因为这两个数据是分别独立获取的，短时间内理论上可能出现进程和端口状态对不上的情况，这也是作者在文档里坦率提到的一个已知限制。
会话数据在连接建立时先做一次初始同步，之后完全依赖 SSE 事件更新，不会有后台定时全量扫描去反复轮询。
OpenCode shim 是怎么工作的
这是 AgentPulse 实现"自动发现"的一个关键设计。安装包在安装时会尝试：
- 查找系统中已安装的 OpenCode 可执行文件
- 在
%LOCALAPPDATA%\AgentPulse\bin生成一个 shim（垫片程序） - 把 shim 目录加进系统 PATH，并且排在 Node.js 目录之前
- 期间可能会弹出 UAC 权限请求
装上 shim 之后，效果是：只有你敲不带任何参数的裸命令 opencode 时，才会被自动加上一个随机的 loopback 端口（等价于 opencode --port <随机端口>），从而让它变成一个可以被 AgentPulse 发现的 Server；而只要命令带了参数（比如 opencode --version、opencode serve、opencode attach ...），shim 都会原样透传给真正的 OpenCode，不做任何干预。shim 内部保存了真实 OpenCode 的目标路径，不会重复走 PATH 查找，避免递归调用自己。
另外，OpenCode 启动或退出时，shim 会通过本机 Named Pipe 给正在运行的 AgentPulse 发一次性通知，触发一次扫描------通知本身不包含任何会话内容，AgentPulse 没运行或者通知失败也完全不影响 OpenCode 正常启动退出。
需要注意的是，普通的 opencode TUI 默认走内部 worker，通常不会暴露外部可访问的 HTTP 端口，这类实例是被有意识地排除在发现范围之外的，只有 opencode serve、opencode web、opencode --port <port> 这几种带监听端口的启动方式才能被发现。
隐私与安全方面的设计
对于这种需要访问其他进程数据的工具，隐私安全通常是大家比较关心的点，AgentPulse 在这块的设计还算克制：
- Server 连接被限制在本机 loopback 地址内
- 不修改 OpenCode 配置文件，不注入任何 OpenCode 插件
- 不使用 WebSocket bridge 传输会话数据
- Named Pipe 仅用于本机的启动/退出通知，使用随机管道名并做 token 校验
- 不会把会话提示词或会话内容上传到远程服务
- 系统 PATH 的修改只在安装 shim 时发生，且需要管理员权限
怎么用起来
直接装安装包 （推荐给普通用户）：从 GitHub Releases 下载类似 AgentPulse-<version>-x64.exe 的安装包，装完基本就能用，shim 会自动配置好。装完/卸载完建议重启一下已经打开的 PowerShell、Windows Terminal 和 VS Code，让它们重新读取 PATH。
从源码跑（适合想改代码或者本身就是折腾党）：
bash
pnpm install
pnpm dev # 启动 Electron 开发模式
pnpm typecheck # TypeScript 类型检查
pnpm test # Vitest 测试
pnpm shim:install # 手动装 shim，需要管理员权限
pnpm build # 构建主进程、预加载脚本和渲染器
pnpm package # 打 Windows NSIS 安装包环境要求也很简单：Windows + Node.js + pnpm 10+，如果只是构建测试代码，甚至不需要本机装 OpenCode。
小结
AgentPulse 解决的是一个很具体、很"手感"层面的痛点：多开 Agent 任务之后如何一眼看清整体进度。它没有走插件注入或者 bridge 转发这种相对"重"的路线，而是选择了基于进程扫描 + 官方 SDK 的旁路观察方式，实现上更轻量，也更不容易因为 OpenCode 自身升级而"水土不服"。目前项目主要面向 Windows 平台，且仓库还没有附带 LICENSE 文件，如果想在生产环境或者对外分发前使用，建议先关注一下作者后续的许可证补充情况。
对于日常需要同时盯多个 OpenCode 会话的开发者来说，这算是一个体积不大但用起来挺顺手的效率工具，感兴趣的话可以去仓库看看：wuiyan/AgentPulse