pi-agent-hud — Pi HUD Extension

pi-agent-hud 是一个 pi-coding-agent 的状态栏扩展，在终端底部实时显示会话信息。

灵感来自 claude-hud。

预览

[claude-sonnet-4-6] pi-mono git:(main) · medium    [████████░░░░░░░░░░░░] 39%    ⏱ 21m
AGENTS.md · skills x5 · ext.tools x2 · ✓ Grep ×10 · ✓ Bash ×3 · ◐ Edit (12s) · ◐ agent (2m 15s)
▸ how to build a REST API with authentication?

安装

方式一：克隆后安装（推荐）

# 1. 克隆仓库
pi install npm:pi-agent-hud

方式二：Claude / Pi 一键安装

在 Claude 或 Pi 对话中直接说：

请帮我安装 pi-agent-hud 扩展到当前项目

方式三：命令行临时加载

pi -e npm:pi-agent-hud

验证安装

pi list

安装后重启 pi 或在会话中输入 /reload 即可激活。

显示内容

Line 1 — 会话概览

[模型名] 项目名 git:(分支) · thinking级别    [████░░░░] 39%    ⏱ 21m

元素	说明
[模型名]	当前 LLM 模型 ID
项目名	当前工作目录名
git:(分支)	Git 分支，非 git 仓库不显示
· medium	Thinking 级别，关闭时不显示
[████░░░░] 39%	Context 窗口使用率进度条
⏱ 21m	会话已运行时长

进度条颜色：0-70% 绿色 / 70-90% 黄色 / 90%+ 红色

Line 2 — 活动详情

AGENTS.md · skills x5 · ext.tools x2 · ✓ Grep ×10 · ◐ Edit (12s) · ◐ agent (2m 15s)

元素	说明
AGENTS.md	检测到的上下文配置文件（绿色）
skills x5	已加载的 skill 数量
ext.tools x2	扩展注册的工具数量
cmds x3	扩展注册的 slash 命令数量
↑12.5k ↓3.2k	Token 明细，默认始终显示，可配置
$0.042	会话累计费用
✓ Grep ×10	已完成工具调用统计，按次数降序
◐ Edit (12s)	正在执行的工具，黄色
◐ agent (2m 15s)	正在运行的 Agent 循环，黄色

Line 3 — 最近输入 + 历史提示

▸ how to build a REST API with authentication?  Ctrl+H:5

元素	说明
▸	指示符
用户文本	最近一次用户输入内容
Ctrl+H:5	历史记录数量提示（仅当历史 ≥ 2 条时显示）

Ctrl+H — 历史记录浮层

按 Ctrl+H 弹出会话输入历史：

┌ Session History ─────────────────────────────────────┐
│ ▸ how to build a REST API with authentication?      │
│   请帮我检查文档                                      │
│   帮我提交一下                                        │
├ ↑↓ scroll · Enter select · Esc close ───────────────┤
└──────────────────────────────────────────────────────┘

按键	功能
↑ / k	上移选择
↓ / j	下移选择
Enter	选中并回填到输入框
Esc / Ctrl+C	关闭浮层

详细文档见 docs/pi-hud.md。

配置

在 .pi/pi-hud.json（项目级）或 ~/.pi/agent/pi-hud.json（全局）中配置：

{
  // Token 显示模式："always" 始终 | "highContext" 仅高占用时
  "tokenMode": "always",
  "tokenThreshold": 85,

  // 显示/隐藏元素
  "disabled": ["extCmds", "cost"],

  // 或只显示指定元素（二选一）
  // "enabled": ["model", "project", "git", "contextBar", "elapsed", "tokens"]
}

可配置元素：

元素	说明	默认
model	模型名称	✅
project	项目目录名	✅
git	Git 分支	✅
thinking	Thinking 级别	✅
contextBar	Context 进度条	✅
elapsed	会话时长	✅
contextFiles	上下文配置文件	✅
skills	Skill 数量	✅
extTools	扩展工具数量	✅
extCmds	扩展命令数量	✅
tokens	Token 明细	✅
cost	费用	✅
rateLimit	⚡ API 额度剩余（Anthropic/OpenAI 自动检测）	✅
toolStats	工具调用统计	✅
runningTools	正在执行的工具	✅
runningAgents	正在运行的 Agent	✅
lastInput	最近输入	✅
historyHint	Ctrl+H 历史提示	✅

完整配置示例见 examples/pi-hud.json。

网格布局

默认单栏模式（不设 layout）和现在完全一样。设置 layout 后启用网格分栏：

{
  // 每行列数数组，最多 5 行，每行 1/2/4 列
  "layout": [1, 2, 2],

  // 把元素钉到指定格子 { line: 行号(0起), col: 列号(0起) }
  // 未列出的元素自动从左到右、从上到下填充
  "placement": {
    "tokens":   { "line": 1, "col": 0 },
    "cost":     { "line": 1, "col": 0 },
    "toolStats": { "line": 1, "col": 1 },
    "lastInput": { "line": 2, "col": 0 },
    "plugin:random-quote": { "line": 2, "col": 1 }
  }
}

渲染效果（layout: [1, 2, 2]）：

Line 1 (全宽):
[claude-sonnet-4-6] pi-agent-hud git:(main) · medium    [████░░] 39%    ⏱ 21m

Line 2 (2列):
AGENTS.md · ↑12.5k ↓3.2k          │  ✓ Grep ×10 · ✓ Bash ×3

Line 3 (2列):
▸ how to build a REST API with auth? │  💬 温故而知新，可以为师矣。—— 孔子

5 行仪表盘（layout: [1, 2, 2, 2, 4]，最多 4×5=20 格）：

Line 1: [全宽]  模型 + 项目 + 进度条 + 时长
Line 2: [2列]   状态信息     │  资源统计
Line 3: [2列]   工具统计     │  运行状态
Line 4: [2列]   最近输入     │  💬 谏言
Line 5: [4列]   col0 │ col1 │ col2 │ col3

布局 Demo 文件：

文件	说明
examples/layout-2col-demo.json	2 列分栏布局
examples/layout-dashboard-demo.json	5 行仪表盘布局

插件系统

用户可以编写自定义插件，向 HUD 添加任何内容。

插件放置在 .pi/pi-hud-plugins/*.js（项目级）或 ~/.pi/agent/pi-hud-plugins/*.js（全局）。

插件接口：

module.exports = {
  name: "my-plugin",        // 唯一名称
  target: "line2",         // "line1" | "line2" | "line3" | "line4" | "line5"
  order: 100,              // 排序，越小越靠前
  col: 0,                  // 可选：网格模式下指定列号

  render(ctx, theme, width) {
    // ctx: 包含所有 HUD 数据
    // theme.fg(color, text): 颜色，color = text|dim|accent|success|warning|error
    // width: 终端宽度
    // 返回 string 显示，undefined 跳过
    return theme.fg("dim", `🔁 ${ctx.inputHistory.length} turns`);
  },
};

示例插件：

文件	功能
examples/turn-counter-plugin.js	显示对话轮次计数
examples/clock-plugin.js	在 Line 1 显示当前时间
examples/context-emoji-plugin.js	用 emoji 替代 context 进度条
examples/quote-plugin.js	每 10 秒随机显示一条谏言 💬

项目结构

pi-agent-hud/
├── extensions/
│   └── pi-hud.ts                  # 扩展源码
├── scripts/
│   └── install.js                 # 安装脚本
├── examples/
│   ├── pi-hud.json                 # 配置示例（全字段）
│   ├── layout-2col-demo.json       # 布局 Demo：2 列分栏
│   ├── layout-dashboard-demo.json  # 布局 Demo：5 行仪表盘
│   ├── turn-counter-plugin.js      # 插件：轮次计数
│   ├── clock-plugin.js             # 插件：时钟
│   ├── context-emoji-plugin.js     # 插件：emoji context
│   └── quote-plugin.js             # 插件：随机谏言
├── docs/
│   └── pi-hud.md                   # 详细文档
├── tsconfig.json
├── package.json
├── README.md
└── README_EN.md

依赖

运行时依赖 pi-coding-agent 的 Extension API：

• @mariozechner/pi-ai
• @mariozechner/pi-coding-agent
• @mariozechner/pi-tui

无需额外安装 npm 包，扩展由 pi 运行时直接加载。

License

MIT