pi-inline-statusline

English | 简体中文

一个为 Pi coding agent 提供的响应式状态栏插件：空间足够时尽量保持单行，空间不足时按完整 segment 换行。

不会出现只显示一半的 segment，也不会静默丢失上下文、Token、费用或扩展状态。每一项都会作为整体移动到下一行，同时保证信息完整和易读性。

宽终端
π • 模型 • 思考等级 • 项目 • 分支 • 工具 • 上下文 • Token • 费用 • 时间 • MCP

窄终端
π • 模型 • 思考等级 • 项目 • 分支
工具 • 上下文 • Token • 费用 • 时间
MCP

为什么维护这个分支

很多状态栏要么直接截断整个 footer，要么始终为扩展状态额外占用一行。pi-inline-statusline 会根据终端当前的可用宽度动态布局：

• 空间足够时保持行内展示：主状态栏和扩展状态完整放得下时，共用同一行。
• 按完整 segment 换行：模型、分支、上下文、Token 和费用等 segment 不会被拆到两行。
• 不丢失信息：超出当前行的内容会移动到下一行，而不是消失在终端边缘。
• 严格控制行宽：包括 ANSI 彩色文本在内，每一行的可见宽度都不会超过终端宽度。
• 响应式扩展状态：MCP 和其他 Pi 扩展状态会优先加入最后一行，只有空间不足时才移动到下方。

功能

• 显示模型和思考等级。
• 显示当前项目目录和 Git 分支。
• 显示精简 Git 状态：领先、落后、已暂存、已修改、未跟踪和冲突。
• 显示正在执行或最近完成的工具。
• 显示上下文窗口占用、Token 总量、预估费用和时间。
• 显示其他 Pi 扩展发布的通用状态。
• 支持自定义或隐藏扩展状态图标。
• 检测重复安装的扩展包。
• 提供 Tokyo Night 和 classic 两种视觉预设。
• 无需配置即可使用。

安装

npm

安装最新稳定版本：

pi install npm:pi-inline-statusline

GitHub

安装最新开发版本：

pi install git:github.com/LuckyYunPeng/pi-inline-statusline

本地开发

pi install /absolute/path/to/pi-inline-statusline

修改本地源码后，在 Pi 中执行 /reload 即可应用变更。

视觉预设

通过 PI_STATUSLINE_PRESET 环境变量选择预设：

PI_STATUSLINE_PRESET=tokyo-night pi
PI_STATUSLINE_PRESET=classic pi

支持的预设：

• tokyo-night：默认预设，灵感来自 Starship Tokyo Night preset，使用 ░▒▓、 Powerline 区块和 Tokyo Night 配色。
• classic：紧凑的 Pi 风格状态栏，使用左对齐的 • 分隔符。

未设置或设置了无效值时，将回退到 tokyo-night。两种预设显示相同的信息和 emoji 标识。

扩展状态图标

扩展状态会根据状态 key 使用内置图标。可以在 ${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-statusline.json 中覆盖或隐藏图标：

{
  "extensionStatusIcons": {
    "caffeinate": "☕",
    "github-pr": "🔎",
    "goal": "🎯",
    "pisync": "☁️",
    "unknown-error-retry": "",
    "plan-mode": "📝",
    "subagents": "🤖",
    "@vendor/pi-foo": "🧪"
  }
}

兼容性：有效的旧配置文件 pi-statusline-settings.json 会自动迁移为 pi-statusline.json。如果两个文件同时存在，新文件优先。

• 精确状态 key 始终优先，例如 "goal" 或 "foo:server"。
• 对于已安装的扩展，可以使用包名或来源，例如 "@vendor/pi-foo"、"npm:@vendor/[email protected]"、"pi-foo" 或派生 key "foo"。
• 命名空间状态 key：包 @vendor/pi-foo 可以匹配 foo、foo:server 和 foo/server，但不会模糊匹配 foobar。
• 未配置时使用内置图标；未知状态 key 使用 🔌。
• 字符串值会作为图标显示。
• 空字符串表示仅显示状态文本，不显示图标。
• 如果多个已安装包派生出同一个 key，请使用精确状态 key 消除歧义。
• PI_STATUSLINE_PRESET 仍是唯一的预设配置；该 JSON 文件只控制扩展状态图标。

在 PI_CAFFEINATE_ICON 的弃用过渡期内，如果 JSON 未配置 caffeinate，仍会使用 pi-caffeinate 提供的前导 emoji。两者同时存在时 JSON 配置优先。

响应式布局

footer 由多个独立 segment 组成：

brand | model | thinking | cwd | branch | tools | context | tokens | cost | time

segment 会从左到右依次加入当前行。如果加入下一个完整 segment 后会超过终端宽度，该 segment 会从下一行开始。只有当单个 segment 本身就比终端更宽时，才允许截断这个 segment。

扩展状态使用相同的可用空间。空间足够时，它们会追加到最后一条状态栏行；否则会从下一行开始，并在需要时安全换行。

默认的 tokyo-night 预设会将每一条换行后的状态栏渲染为独立、完整闭合的 Powerline。classic 预设使用简单分隔符，但采用相同的布局规则。

Git 状态

仓库干净时不会显示 Git 状态标记。出现标记时含义如下：

• ⇡ 领先
• ⇣ 落后
• + 已暂存
• ~ 已修改或删除
• ? 未跟踪
• ! 冲突

示例：🌿 main ⇡1 +2 ~1 ?3。

扩展状态示例

pi-inline-statusline 使用 Pi 通用扩展状态 API，不依赖特定的状态生产扩展：

• 🎯 active：goal: active 使用内置 goal 图标。
• 🔎 PR #123 checks passing：github-pr 状态使用内置图标。
• ☕ display：JSON 中配置 "caffeinate": "☕"。
• 🧪 running：已安装包名为 @vendor/pi-foo，JSON 中配置 "@vendor/pi-foo": "🧪"。
• receiving：JSON 中配置 "unknown-error-retry": ""，隐藏图标。
• 🔌 running：未知扩展状态 key 且没有配置图标。
• ⚠️ dup biome-lsp：检测到同一个扩展通过多个来源重复安装。

包结构

pi-inline-statusline/
├── src/
│   ├── statusline.ts  # Pi 入口和监听器生命周期
│   └── *.ts           # Git、扩展状态、配置和渲染模块
├── presets/
│   ├── ansi.ts
│   ├── classic.ts
│   ├── tokyo-night.ts
│   └── types.ts
├── README.md
├── README.zh-CN.md
├── LICENSE
├── tsconfig.json
└── package.json

只有 statusline.ts 是 Pi 入口，其他源码模块均为包内实现。package.json 通过以下配置声明 Pi 扩展：

{
  "pi": {
    "extensions": ["./src/statusline.ts"]
  }
}

上游与许可证

本项目是 @narumitw/pi-statusline 的社区维护分支，保留了上游包的 Git 历史，并由 LuckyYunPeng/pi-inline-statusline 独立维护。

项目使用 MIT 许可证，详情见 LICENSE。