pi-hud-footer

English | 简体中文

一个给 pi coding agent 使用的 Claude HUD 风格自定义 footer/statusline 插件。

Fork 说明:本仓库是 Agents365-ai 维护的 fork,基于上游 liao666brant/pi-hud-footer 0.7.0(MIT)。除上游功能外,额外提供 tmux jobs 行与 rtk / MCP / 项目记忆扩展行,差异与上游同步方式见 FORK.md。

安装:pi install git:github.com/Agents365-ai/pi-hud-footer@v1.0.0;已在 npm 发布时也可用 pi install npm:@agents365-ai/pi-hud-footer@1.0.0。 项目内临时试用:pi -e .

它把模型、上下文、词元、缓存、费用、工具调用和运行状态集中显示在 TUI 底部。默认使用 classic 经典 footer 样式；也可以切换到 border 输入框边框样式，把稳定信息嵌入输入框边框，只把会动态增长的工具统计保留在 footer 中。

功能亮点

• 显示当前模型、思考等级、项目名和 git 分支
• 显示上下文使用进度、可选会话树/当前分支的累计词元用量、输出速率、缓存读写和缓存命中率
• 支持累计或最近一次请求的缓存命中率
• 显示 running / ready 状态、会话耗时和费用估算；每轮用时通知可选开启
• 费用支持 USD / CNY 显示，美元兑人民币汇率默认 6.8 且可自定义
• 显示工具调用统计，并保持 footer 高度稳定
• 显示 tmux jobs 行：pi-agent socket 上带 PI_HUD_OWNER 标记的 pane，最多三行，条目数由 jobsMax 控制
• 扩展行显示 rtk 本会话节省、MCP 服务与工具数、项目记忆条数，源不存在时自动隐藏
• 支持两套 HUD 样式：classic 经典 footer 样式和 border 输入框边框样式
• 支持中文/英文界面，默认根据系统语言自动选择
• 支持全局和项目级 JSON 配置

主题 / 样式

样式	别名	适合场景	说明
classic	1	默认主题	将 HUD 信息集中显示在输入框下方，保留经典三行 footer 体验。
border	2	边框布局	将模型、耗时、费用、上下文、词元和状态嵌入输入框上下边框；工具统计保留在 footer 行，布局更稳定。

在 TUI 中切换并保存样式：

/hud-footer-theme

命令会写入配置文件：如果当前受信任项目已存在 .pi/hud-footer.json，则保存到项目配置；否则保存到全局配置 ~/.pi/agent/hud-footer.json。也可以手动设置：

{
  "style": "classic"
}

classic / 1：经典 footer 样式

border / 2：输入框边框样式

安装

从 GitHub 安装，用 tag 固定版本：

pi install git:github.com/Agents365-ai/pi-hud-footer@v1.0.0

npm 发布后也可从 npm 安装：

pi install npm:@agents365-ai/pi-hud-footer@1.0.0

本地开发或调试时，可以从本地路径安装：

pi install /path/to/pi-hud-footer

不安装、直接加载仓库目录：

pi -e .

基础扩展来自上游 liao666brant/pi-hud-footer，本 fork 的差异见顶部 Fork 说明。

命令

命令	说明
/hud-footer	切换当前会话的 HUD footer 开/关。
/hud-footer-reload	重新读取配置并刷新 HUD footer。
/hud-footer-theme	打开 TUI 选择器，切换并保存 HUD 样式。
/hud-footer-language	打开 TUI 选择器，切换并保存界面语言。
/hud-footer-currency	打开 TUI 选择器，切换并保存费用显示货币（汇率仍在配置文件中设置）。

配置

完整配置说明见：docs/CONFIG.md / English

示例配置：examples/hud-footer.json / 带注释版：examples/hud-footer.jsonc

配置层级	路径	说明
全局配置	~/.pi/agent/hud-footer.json	对所有会话生效。
项目配置	.pi/hud-footer.json	仅在项目受信任时读取，并覆盖全局配置。

配置项

配置项	说明
enabled	是否启用 HUD footer。
language	界面语言：auto / zh / en。
style	HUD 样式：classic / border。
display	控件显示规则，支持全局和按样式覆盖。
cacheRateMode	缓存命中率：累计值 total / 最近一次请求 latest，默认 total。
currency	费用显示货币：USD / CNY，默认 USD；也可用 /hud-footer-currency 切换。
exchangeRate	美元兑人民币汇率，默认 6.8（即 1 USD = 6.8 CNY）。
barWidth	上下文进度条宽度。
maxTools	工具统计最多显示数量。
jobsMax	tmux jobs 行最多显示多少个 pane，默认 10，运行中的 pane 优先。
usageScope	累计词元和费用范围：当前分支 branch / 完整会话树 session，默认 branch。

display 支持 all、classic、border 分组，可配置：toolsLine、modelName、thinkingLevel、projectName、gitBranch、context、tokens、tokenBreakdown、tokenRate、cacheRate、elapsed、cost、state、turnDuration、rtkSavings、mcpStatus、memoryCount。

turnDuration 默认关闭，避免与其他插件提供的每轮耗时通知重复；需要时将其设置为 true。

rtkSavings、mcpStatus、memoryCount 控制扩展行中的三段，默认开启，各自在数据源不存在时自动隐藏；细节见 docs/CONFIG.md 的「扩展行」。

修改配置后，在 pi 中执行：

/hud-footer-reload

或：

/reload

指标说明

词元指标使用以下图标：

图标	含义
↑	输入词元
↓	输出词元
R	缓存读取词元
W	缓存写入词元
⚡	缓存命中率

R / W 在对应数值为 0 时会分别隐藏。

usageScope 决定 ↑/↓/R/W 与费用是累计完整会话树还是当前分支；session 会计入 assistant、带 usage 的 toolResult、usage 记录（如缓存预热）、compaction 和 branch summary。上下文进度和工具统计仍分别使用当前有效上下文与当前分支。

tokenRate 显示主 agent 当前流式输出速率，按最近 0.5～2 秒输出词元增量计算。

cacheRateMode 可选择最近一次 assistant 请求（latest）或累计值（total）；latest 取当前统计范围内最后一条 assistant 请求，total 取当前统计范围的累计值。缓存命中率计算方式：

cacheRead / (input + cacheRead + cacheWrite)

即：缓存命中的输入词元 / 输入侧总词元。

扩展行包含 rtk 本会话节省、MCP 服务与工具数、项目记忆条数三段，每段在数据源缺失时自行隐藏。tmux jobs 行显示 pi-agent socket 上带 PI_HUD_OWNER 标记的 pane，每项形如 名称(命令)，最多三行，条目数由 jobsMax 控制，运行中的 pane 优先，放不下的以 +N 标在行尾。采集时机、来源文件与边界条件见 docs/CONFIG.md。

开发 / 临时运行

不安装，临时加载：

pi -e ./pi-hud-footer

在仓库目录内：

pi -e .

修改后在 pi 中执行：

/reload

发布给其他人

详见 FORK.md 的「Install and publish」一节。

安全说明

pi 扩展会以你的系统权限运行。本扩展不访问网络，但会读取本机文件并运行少量命令：

• 通过 tmux -L pi-agent list-panes 读取 pi-agent socket 上的 pane 信息，不读取文件；
• 读取 ~/.pi/agent/mcp.json、~/.pi/agent/mcp-adapter.json、~/.pi/agent/mcp-cache.json，以及 ~/.pi/agent/memory/<slug>/ 下的项目记忆存储；
• 运行 rtk gain -f json 与 git rev-parse --show-toplevel。

许可证

MIT