macOS local agent monitor

HUD

用一个透明桌面浮窗看住所有 coding TUI：Claude、Trae CLI、coco 或任意 shell alias。 不抢终端输入，只展示最新有效内容和当前状态。

开始使用 GitHub

CLI 仍是主入口

继续在原终端里工作，`hud` 只包一层 PTY，记录 session、原始输出和来源 App。

Server 负责解析

`hud-server` 维护 terminal replay 和状态判断，升级 parser 后只需 `hud server restart`。

UI 只做展示

SwiftUI 读取 display registry，支持透明模式、亮暗色、点击跳回来源 App。

安装与运行

Python CLI 使用 uv 安装，macOS HUD UI 使用 Swift 构建。

uv sync
uv tool install -e . --force
uv tool update-shell
scripts/build-app.sh
open dist/hud-ui.app

常用命令

非内置命令都会作为外部 TUI 处理，alias 和函数也可以通过交互 shell 解析。

hud claude --resume <id> hud traecli hud Claude hud ttadk ... hud list --json hud server restart

状态识别

HUD 会优先展示对用户有行动价值的内容，而不是 spinner、thinking 或终端重绘残片。

新session 已创建，还没有稳定输出。
工作中正在执行命令、读取文件或生成改动。
已完成出现总结、recap、完成提示或最终结果。
需处理问题出现确认框、权限选择、错误或需要用户输入。
停止进程已退出或 session 过期。

本地架构

所有数据保存在本机，UI 不依赖 Python runtime，也不接管 TUI 输入。

hud CLI
PTY raw snapshot
hud-server parser
hud-ui