并行跑 Agent 时，别再靠切窗口找卡点：用 AI Pulse 把本地状态收敛到 macOS Dock 旁
当 Claude Code 或其他编程 Agent 同时跑在几个仓库里，真正拖慢节奏的常常不是生成代码，而是状态不可见：一个会话已经结束，另一个在等待权限，第三个因为错误停住。终端标签页、编辑器窗口和通知中心各自保存一部分信号；人只能不断切换窗口确认，结果是本应几秒钟处理的审批请求，可能被搁置十分钟。
AI Pulse 是一个面向 macOS 的本地状态指示应用。它不尝试替代 Agent，也不读取提示词或终端内容；它的工作是把多个本地 Agent 的状态汇总成 Dock 旁一条八灯的细窄指示条。对于把并行 Agent 当作日常开发方式的人，这是一种很小、却很实用的可观测性层。
先解决“哪一个需要我”的问题
AI Pulse 使用一个聚合信号，而不是同时展示每个模型的长文本日志。README 定义了六类视觉状态：工作中是青色移动光点；等待输入或审批时是橙色呼吸灯；失败时双闪红色；完成后是稳定绿色；空闲时呈蓝绿色缓慢变化；没有连接时熄灭。
这种设计的重点不是用颜色替代日志，而是降低第一次判断的成本。你只需扫一眼 Dock 附近，就能决定要不要回到某个 Agent；真正需要诊断时，再打开对应的终端或编辑器。对于同时运行构建、重构和测试任务的场景，这比让每个会话各自弹通知更少打断，也避免“所有完成消息看起来同样紧急”的问题。
应用提供 Reduce Motion 静态呈现，并保留可选的原有图标指示样式。它不是嵌入 Dock 的私有扩展：项目明确说明，macOS 没有公开 Dock accessory API。AI Pulse 使用公开的屏幕几何信息，以无边框、非激活的 NSPanel 放在 Dock 邻近区域，因此不需要 Accessibility、屏幕录制权限或注入机制。这也是把它用于日常工作机时值得优先核实的边界。
本地事件服务：状态来自哪里
AI Pulse 启动后会在本机回环地址 127.0.0.1:7455 提供事件服务；端口可在设置中调整。它只监听 loopback，而不是暴露给局域网。应用把 bearer token 存入 macOS Keychain，并将供 CLI 使用的配置写到 ~/Library/Application Support/AIPulse/cli.json，该文件权限为 0600。这样，日常命令不必在 shell 历史里携带令牌。
项目内置的 aipulse CLI 可以新增、更新和删除某个 Agent 的状态。下面的流程使用 README 给出的命令形式；$SESSION_ID 应是调用方为一次会话保存的稳定标识，而 $PWD 让不同仓库的同类会话不相互覆盖：
aipulse agent upsert \ --id "claude-code:$PWD:$SESSION_ID" \ --name "Claude Code" \ --provider anthropic \ --instance "$(basename "$PWD")" \ --state working \ --message "正在实现 Dock 放置逻辑" aipulse agent update \ --id "claude-code:$PWD:$SESSION_ID" \ --state waitingForInput \ --message "等待权限确认" \ --sequence 2 aipulse agent remove --id "claude-code:$PWD:$SESSION_ID" aipulse agents
这里有两个容易被忽略的工程细节。第一，更新沿用相同 --id，否则每一次状态变化都会被当成新的 Agent。第二，--sequence 让事件有明确顺序；当异步钩子或多个进程同时上报时，较早到达或重复到达的事件不应覆盖更晚的状态。README 中的事件端点也与 CLI 行为对应：创建或更新为 POST /v1/agents/upsert，事件更新为 POST /v1/agents/{id}/event，健康检查是 GET /v1/health。
让 Claude Code 自动上报，而不是手动敲命令
手动调用 CLI 适合先验证布局和团队约定；持续使用时，更合理的入口是 Claude Code hook。AI Pulse 提供 aipulse claude-hook：项目说明它会将 SessionStart 映射为空闲、UserPromptSubmit 和 PreToolUse 映射为工作中、PermissionRequest 映射为需要审批、Stop 映射为完成、StopFailure 映射为失败，而 SessionEnd 会移除条目。
系统级使用可以先构建 release CLI，再在 Claude Code 的用户级设置中注册相同 hook。项目给出的安装步骤如下：
swift build -c release sudo cp .build/release/aipulse /usr/local/bin/
随后把 aipulse claude-hook 配置到 ~/.claude/settings.json 的相应 hook 事件中。首次加载项目 hook 时，Claude Code 会要求批准；这是应保留的人工确认点。不要为了方便把一个来源不明的 hook 直接写进全局配置，因为 hook 能在工作流关键节点执行本地命令。
AI Pulse 的 hook 设计也有值得借鉴的最小化原则：它不解码提示词、工具输入或助手输出，只发布状态。因此指示条能告诉你“需要回来处理”，却不能成为另一个泄露代码与上下文的旁路日志。
状态汇总不等于监控一切
项目的状态优先级和失效策略决定了指示灯不能永远显示过时的“工作中”。README 说明，长时间没有上报的工作状态会先转为过时、之后转为断开；底层进程已经退出的条目也会在一次扫描内降级。已完成的会话会在配置的延迟后过期，而等待输入、等待审批和失败不会被计时器自动清掉。这一差异符合人的注意力模型：前者可能只是旧心跳，后者往往仍需要处理。
它也不是万能的 Agent 监控平台。当前内置适配重点是 Claude Code；其他 Agent 若要接入，需要通过 CLI 或本地 HTTP 事件模型自行发布状态。灯条给的是聚合态，不能代替日志、成本追踪、执行审计或任务依赖图。若团队需要跨机器、跨成员的完整治理，应使用带身份、审计和权限模型的系统；AI Pulse 更适合单台 macOS 工作机上的“抬头可见”反馈。
一套可落地的接入顺序
不要一开始就把所有会话都接进来。先在一个非关键仓库启动应用，执行 aipulse agents，然后只为一个 Claude Code 会话启用 hook。依次制造三个可观察事件：让 Agent 执行一个短任务、让它停在一个需要确认的权限步骤、最后正常结束。每个阶段都同时检查终端实际状态和灯条状态，确认状态语义没有被团队的工作流误用。
第二步才是约定 ID。推荐把 provider、仓库路径和会话标识组合为一条稳定键，例如示例中的 claude-code:$PWD:$SESSION_ID。仓库路径用于隔离项目，会话标识用于隔离同一仓库中的并发任务。不要用“当前任务名称”作为唯一 ID：任务名会变化，重试时也容易让旧状态残留。对于你自己写的适配器，所有更新都应附带单调递增的 sequence；网络或进程调度导致乱序时，接收端才有机会拒绝旧事件。
第三步是给“等待”设计明确含义。把需要人工批准、需要补充需求、需要解锁密钥这几种情形都映射到等待状态，确实能提升可见性；但不要把长时间运行的构建也误报为等待。前者要求人介入，后者只需要继续观察。状态模型越少越好，不过每个状态必须能导向一个明确动作：继续等、打开会话、处理失败，或忽略已完成任务。
最后，为退出路径做演练。关闭终端、终止会话和休眠唤醒都可能留下过时条目。AI Pulse 已对工作中与完成状态设置了老化/过期处理，但适配器仍应在会话结束时发送移除事件。只有“正常路径会登记、异常路径会清理”同时成立，桌面上的绿色或橙色灯才不会逐渐失去可信度。
它也不是万能的 Agent 监控平台。当前内置适配重点是 Claude Code；其他 Agent 若要接入，需要通过 CLI 或本地 HTTP 事件模型自行发布状态。灯条给的是聚合态，不能代替日志、成本追踪、执行审计或任务依赖图。若团队需要跨机器、跨成员的完整治理，应使用带身份、审计和权限模型的系统；AI Pulse 更适合单台 macOS 工作机上的“抬头可见”反馈。
安装前的现实边界
发布包从项目的 latest release 获取，解压后将 AI Pulse.app 放入 /Applications。项目当前说明发布包尚未 notarize：首次启动要右键选择“打开”，macOS 15 及更高版本还可能需要在“隐私与安全性”中允许。对安全敏感的机器，这意味着应先审阅仓库、构建脚本和发布产物，再决定是否安装，而不是把“开源”误当作自动可信。
从源码构建需要 macOS 14+、Xcode 16+ 与 Swift 6 工具链；基本验证命令为 swift test，本地服务健康检查为 swift run aipulse health。项目采用 MIT 许可证，仓库公开标明其为 Swift/SwiftUI 实现。
把 Agent 从“看不见的后台任务”变成低干扰的环境信号，并不会减少失败本身，却能缩短从失败、完成或审批发生到人注意到它的时间。若你的瓶颈正是并行会话的上下文切换，AI Pulse 这种本地、最小权限、只传状态的做法，比再加一个聊天机器人通知更贴近问题本身。