如何5分钟安装并跑通Agent HUD:面向新手的最快上手指南
如何5分钟安装并跑通Agent HUD:面向新手的最快上手指南
Agent HUD 是一款面向编程智能体(coding agent)的 HUD 状态面板工具,能一屏盯住 Claude Code、Codex 等 27+ 编码助手的额度(quota)、token 消耗与会话状态,支持 Mac、Windows、Linux 桌面端,还能同步到手机与手表。本文教你用最少的命令完成 Agent HUD 安装,5 分钟从零跑通第一个界面。
一、Agent HUD 是什么?新手先花10秒了解
简单说,Agent HUD 就像给屏幕加装了一个"驾驶舱仪表盘":你的编码 agent 在后台干活,屏幕边缘的小面板用颜色告诉你——绿色额度充足、黄色接近上限、红色即将用完;agent 需要批准操作时,你不必切回终端,直接在面板上点"允许一次"。
下面这张图是它的完整演示:Notch 模式下呼吸的光圈代表额度,悬停展开各 agent 的配额与 token 统计,agent 提出请求时直接在 HUD 上回答:
它是用 Tauri 2 构建的(Rust 内核 + React 界面),跨平台且轻量,详见 docs/platform-architecture.md。
二、安装前检查:3个环境条件
开始 Agent HUD 快速上手 前,先确认你的环境:
| 安装方式 | 需要 | 适合人群 |
|---|---|---|
| 官方命令安装(推荐) | macOS 14+ / Windows / Linux x86_64,有 Node.js | 绝大多数新手 |
| Homebrew 安装 | 仅 Mac,已装 Homebrew | Mac 用户 |
| 源码构建 | Node.js 24+、pnpm、Rust 1.90+ 工具链 | 开发者 |
💡 前两种方式不需要任何编程基础,一条命令即可。
三、三步完成 Agent HUD 安装
3.1 macOS:一条 brew 命令装好
打开"终端",执行:
brew install --cask jazzenchen/tap/agent-hud
如果应用已经在 /Applications 里,加一个参数即可接管:
brew install --cask jazzenchen/tap/agent-hud --adopt
装完后 Mac 上的 Agent HUD 会自动更新自己。
3.2 Windows / Linux:npx 一键安装命令
只要有 Node.js,任意平台执行同一句命令:
npx @agenthud/install
它会从官方 release 自动下载对应系统的安装包(含测试版),并用 SHA256 校验后再安装。各系统实际发生的事:
- macOS:把
Agent HUD.app放入/Applications,先校验 Developer ID 签名; - Windows:自动运行安装程序(注意目前为未签名的测试构建);
- Linux x86_64:安装到
~/Applications/Agent-HUD.AppImage(部分系统需要 FUSE 2,即libfuse2)。
常用可选参数(完整说明见 src/apps/installer/README.md):
| 参数 | 作用 |
|---|---|
--release <version> |
安装指定版本,而不是最新版 |
--dir <folder> |
指定安装目录(Mac/Linux 无写权限时) |
--no-open |
安装完不自动打开应用 |
3.3 进阶:从源码构建自己的 Agent HUD
想参与贡献或尝鲜最新代码?按 README.md 的步骤:
git clone https://gitcode.com/gh_mirrors/ag/agent-hud-open
cd agent-hud-open
pnpm install
pnpm run check
pnpm run build:macos -- --bundle
Windows 和 Linux 分别改用 build:windows、build:linux,构建产物位于 target/release/bundle。没有装任何 agent 也能体验:加 --demo 启动,会直接用样例数据打开。
四、跑通验证:第一次启动后看什么
安装完成后打开 Agent HUD,按这个清单确认"跑通":
- 找到你的 agent:装好并登录过的编码工具(如 Claude Code、Codex)会被自动发现,HUD 面板上出现对应的"机器人"头像;
- 看颜色:光圈的绿/黄/红对应额度低于 70%、70%–90%、90% 以上;
- 试一次交互:agent 提出需要批准的请求时,在面板上直接 Approve / Deny;
- 打开统计窗口:查看 token 用量、成本与历史趋势。
Simple 模式则是悬浮在屏幕任意边缘的小面板,每个 agent 头像外圈就是它的额度环:
没有 agent 在手?源码构建加 --demo,或直接看下面两张统计窗口的样例数据效果:
五、装完还能解锁什么
- 手机端同步:同一网络下,iPhone/Apple Watch 免费查看桌面端的额度、统计与会话;
- agent 互发消息:内置 MCP 服务让 Claude Code 修完代码后让 Codex 帮忙 review,详见 docs/agent-messages.md;
- 自定义 HUD:通过 MCP 工具让 agent 自己调整面板布局与展示内容。
手机端统计效果(iPhone Duo 展开屏示例):
六、新手常见问题 FAQ
Q1:安装后面板没出现? 检查 Settings → Display,可以为每块屏幕单独开关 HUD、消息与请求;Notch 模式只在有刘海的 Mac 上默认可用,其他屏幕请用 Simple 模式。
Q2:Windows/Linux 版本能用吗? 可以,但目前是未签名的测试构建(preview),功能以 docs/platforms.md 的对照表为准;macOS 是功能最完整的正式平台。
Q3:会上传我的数据吗? 不会。会话记录只读你本机已有的文件,用量历史存在本地 SQLite 数据库;从这个源码构建的应用不上传任何数据。
Q4:如何更新?
Mac 上自动更新;Windows/Linux 重新执行一次 npx @agenthud/install 即可。
Q5:语言能切中文吗? 可以,Settings → General → Language,支持简中、繁中、日、韩等 9 种语言。
总结
| 步骤 | 命令/操作 | 耗时 |
|---|---|---|
| 1. 安装 | npx @agenthud/install(或 brew 命令) |
约 2 分钟 |
| 2. 打开应用 | 自动弹出或从程序列表启动 | 10 秒 |
| 3. 确认 agent 被识别 | 看 HUD 面板上的头像与光圈 | 1 分钟 |
| 4. 打开统计窗口 | 查看 token 与成本 | 1 分钟 |
全程不超过 5 分钟。Agent HUD 安装完成后,它几乎不占资源(空闲时约 7% 单核 CPU),安静地守在屏幕边缘,让你的编码 agent 状态从此一目了然。




