---
slug: "pi-agent-hud"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/dafei1288/pi-hud@master/README.md"
repo: "https://github.com/dafei1288/pi-hud"
source_file: "README.md"
branch: "master"
---
# pi-agent-hud — Pi HUD Extension

pi-agent-hud 是一个 [pi-coding-agent](https://github.com/nicholasgasior/pi) 的状态栏扩展，在终端底部实时显示会话信息。

灵感来自 [claude-hud](https://github.com/jarrodwatts/claude-hud)。

![](https://github.com/dafei1288/pi-hud/raw/HEAD/docs/intro.png)

## 预览

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

## 安装

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

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

### 方式二：Claude / Pi 一键安装

在 Claude 或 Pi 对话中直接说：

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

### 方式三：命令行临时加载

```bash
pi -e npm:pi-agent-hud
```

### 验证安装

```bash
pi list
```

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

## 显示内容

### Line 1 — 会话概览

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

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

进度条颜色：<font color="green">0-70% 绿色</font> / <font color="orange">70-90% 黄色</font> / <font color="red">90%+ 红色</font>

### 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` 弹出统一浮层，`Tab` 键在**历史记录**和**执行计划**之间切换：

**历史记录页（默认）：**

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

| 按键 | 功能 |
|------|------|
| `↑` / `k` | 上移选择 |
| `↓` / `j` | 下移选择 |
| `Enter` | 选中并回填到输入框 |
| `Tab` | 切换到执行计划页 |
| `Esc` / `Ctrl+C` | 关闭浮层 |

**执行计划页（Tab 切换）：**

```
┌ History (Tab)  [ Plan ] ───────────────────────────────┐
│ 🎯 how to build a REST API                              │
│ 📋 12 turns                                             │
├─────────────────────────────────────────────────────────┤
│ 📊 📖×5  ✎×3  🔍×2  ⚙×2                                │
├─────────────────────────────────────────────────────────┤
│ 🕐 Tool call timeline                                   │
│   ✓ 🔍 grep · extension                                 │
│   ✓ ✎ edit · extensions/pi-agent-hud.ts                │
│   ◐ ⚙ bash · npm build (12s)                           │
├─────────────────────────────────────────────────────────┤
│ 💬 Turn log                                             │
│ T01 I'll start by reading the project structure         │
│ T02 Let me search for the relevant files...             │
│ T03 I'll make the changes to the extension...           │
└ Esc close ─────────────────────────────────────────────┘
```

| 按键 | 功能 |
|------|------|
| `Tab` | 切换回历史记录页 |
| `Esc` / `Ctrl+C` | 关闭浮层 |

**计划页详情：**

- **📊 分类统计** — 读/搜/写/执行/网络各类工具使用次数
- **🕐 工具时间线** — 最近工具调用序列，✓完成/◐运行中 + 耗时
- **💬 Turn log** — 每轮 agent 回复摘要，最多显示最近 10 轮
- **Agent 计划**（如有结构化步骤）— 步骤进度 + Subagent 委派状态

详细文档见 [docs/pi-agent-hud.md](https://github.com/dafei1288/pi-hud/blob/HEAD/docs/pi-agent-hud.md)。

## 配置

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

```jsonc
{
  // 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-agent-hud.json](https://github.com/dafei1288/pi-hud/blob/HEAD/examples/pi-agent-hud.json)。

## 网格布局

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

```jsonc
{
  // 每行列数数组，最多 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](https://github.com/dafei1288/pi-hud/blob/HEAD/examples/layout-2col-demo.json) | 2 列分栏布局 |
| [examples/layout-dashboard-demo.json](https://github.com/dafei1288/pi-hud/blob/HEAD/examples/layout-dashboard-demo.json) | 5 行仪表盘布局 |

## 插件系统

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

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

**插件接口：**

```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](https://github.com/dafei1288/pi-hud/blob/HEAD/examples/turn-counter-plugin.js) | 显示对话轮次计数 |
| [examples/clock-plugin.js](https://github.com/dafei1288/pi-hud/blob/HEAD/examples/clock-plugin.js) | 在 Line 1 显示当前时间 |
| [examples/context-emoji-plugin.js](https://github.com/dafei1288/pi-hud/blob/HEAD/examples/context-emoji-plugin.js) | 用 emoji 替代 context 进度条 |
| [examples/quote-plugin.js](https://github.com/dafei1288/pi-hud/blob/HEAD/examples/quote-plugin.js) | 每 10 秒随机显示一条谏言 💬 |

## 项目结构

```
pi-agent-hud/
├── extensions/
│   └── pi-agent-hud.ts            # 扩展源码
├── scripts/
│   └── install.js                 # 安装脚本
├── examples/
│   ├── pi-agent-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-agent-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