useful-pi-extensions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 reedchan7
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# useful-pi-extensions
+
+English | [中文](README_CN.md)
+
+A small collection of [pi](https://pi.dev) extensions, installed with one command.
+
+```sh
+pi install git:github.com/reedchan7/useful-pi-extensions
+```
+
+## What is in here
+
+| Extension                                       | What it does                                                                                                                                                                                            |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`statusline`](extensions/statusline/README.md) | Replaces pi's footer with a labelled two-row one: context pressure as a fixed-size meter, cache and cost, the model and effort level, and the latest turn's TTFT and decode throughput in tokens/second |
+
+Only one extension owns the footer, so `statusline` is a complete replacement rather than an
+addition. If you want pi's stock footer back, remove this package and `/reload`.
+
+## Screenshots
+
+### statusline
+
+<img width="897" height="45" alt="Warp 2026-09-18 16 20 27" src="https://github.com/user-attachments/assets/7ae64213-cb05-4440-835e-a633796a87f9" />
+
+## Install
+
+```sh
+# from the repository
+pi install git:github.com/reedchan7/useful-pi-extensions
+
+# pinned to a tag
+pi install git:github.com/reedchan7/useful-pi-extensions@v0.1.0
+
+# from a local checkout (development)
+pi install /absolute/path/to/useful-pi-extensions
+```
+
+Then reload pi in the running session with `/reload`, or start a new one.
+
+> **Removing a loose copy first.** If you were running the extension as a single file in
+> `~/.pi/agent/extensions/`, delete that file before installing this package. Both would load, and
+> two footers race for the same slot — the later one wins, which decides nothing useful.
+
+## Requirements
+
+- pi 0.85 or newer (`pi --version`)
+- No runtime dependencies. `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` are
+  peer dependencies supplied by pi itself.
+
+## Layout
+
+```
+extensions/            # each subdirectory is one extension; pi discovers <name>/index.ts
+  statusline/
+    index.ts           # pi entry point: events and footer wiring
+    render.ts          # pure helpers: number formatting, the meter, row layout
+    render.test.ts     # unit tests for render.ts
+```
+
+`package.json` declares `"pi": { "extensions": ["./extensions"] }` and carries the `pi-package`
+keyword so the package is discoverable. pi resolves the manifest, finds every
+`extensions/*/index.ts`, and loads it — no build step, no bundling.
+
+## Development
+
+```sh
+make install      # bun install
+make check        # every gate: format, lint, types, docs pairing, tests
+make hooks        # install the git hooks (run once, needs a git checkout)
+make help         # list every target
+```
+
+`make check` runs the same gates as CI:
+
+| Gate   | Command              | What it enforces                                                                                                                                                       |
+| ------ | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Format | `bun run fmt:check`  | oxfmt: 100 columns, single quotes, no semicolons                                                                                                                       |
+| Lint   | `bun run lint`       | oxlint in type-aware mode with `--deny-warnings`, so a warning fails the run                                                                                           |
+| Types  | `bun run typecheck`  | `--strict` plus `noUncheckedIndexedAccess`, `exactOptionalPropertyTypes` and `verbatimModuleSyntax`, which is what keeps every file loadable by pi without a transform |
+| Docs   | `bun run docs:check` | every `README.md` has a `README_CN.md` with the same heading sequence and a working language switcher                                                                  |
+| Tests  | `bun test`           | the unit tests under `extensions/*/`                                                                                                                                   |
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/): the `commit-msg` hook
+rejects a subject that is not `type(scope): summary`, and the pre-commit hook formats and lints only
+the staged files. The toolchain is pinned to exact versions in `package.json` (`bunfig.toml` sets
+`install.exact = true`). The `@earendil-works/*` packages are deliberately left at `*`: they are the
+host API pi supplies, and tracking it is what surfaces an upstream break early.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/README_CN.md

@@ -0,0 +1,89 @@
+# useful-pi-extensions
+
+[English](README.md) | 中文
+
+一组 [pi](https://pi.dev) 扩展，一行命令即可安装。
+
+```sh
+pi install git:github.com/reedchan7/useful-pi-extensions
+```
+
+## 包含什么
+
+| 扩展                                               | 作用                                                                                                                                           |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`statusline`](extensions/statusline/README_CN.md) | 替换 pi 的 footer，改成带文字标签的两行：上下文压力用固定宽度仪表显示，外加缓存与花费、模型与思考等级，以及最近一轮的 TTFT 和解码速度（tok/s） |
+
+footer 只能有一个扩展占用，所以 `statusline` 是**替换**而不是叠加。想回到 pi 原生 footer，移除本包再 `/reload`。
+
+## 效果图
+
+### statusline
+
+<img width="897" height="45" alt="Warp 2026-09-18 16 20 27" src="https://github.com/user-attachments/assets/7ae64213-cb05-4440-835e-a633796a87f9" />
+
+## 安装
+
+```sh
+# 从仓库安装
+pi install git:github.com/reedchan7/useful-pi-extensions
+
+# 锁定标签
+pi install git:github.com/reedchan7/useful-pi-extensions@v0.1.0
+
+# 从本地检出安装（开发用）
+pi install /absolute/path/to/useful-pi-extensions
+```
+
+然后在运行中的会话里执行 `/reload`，或直接新开一个会话。
+
+> **先删掉散装的那份。** 如果你之前把扩展作为单文件放在 `~/.pi/agent/extensions/`，
+> 安装本包之前请先删掉那个文件。两份会同时加载，两个 footer 抢同一个位置——
+> 后加载的赢，而谁后加载没有意义。
+
+## 环境要求
+
+- pi 0.85 或更新（`pi --version`）
+- 无运行期依赖。`@earendil-works/pi-coding-agent` 与 `@earendil-works/pi-tui` 是 peer
+  dependency，由 pi 自身提供。
+
+## 目录结构
+
+```
+extensions/            # 每个子目录是一个扩展；pi 发现 <name>/index.ts
+  statusline/
+    index.ts           # pi 入口：事件与 footer 接线
+    render.ts          # 纯函数：数字格式化、仪表、行布局
+    render.test.ts     # render.ts 的单元测试
+```
+
+`package.json` 声明 `"pi": { "extensions": ["./extensions"] }`，并带 `pi-package` 关键字以便被发现。
+pi 读取该清单，找到每个 `extensions/*/index.ts` 并加载——无构建、无打包。
+
+## 开发
+
+```sh
+make install      # bun install
+make check        # 全部门禁：格式、lint、类型、文档配对、单测
+make hooks        # 安装 git hooks（只需一次，需要已 git init）
+make help         # 列出所有目标
+```
+
+`make check` 与 CI 跑同一套门禁：
+
+| 门禁 | 命令                 | 强制内容                                                                                                                                             |
+| ---- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 格式 | `bun run fmt:check`  | oxfmt：100 列、单引号、无分号                                                                                                                        |
+| Lint | `bun run lint`       | oxlint 类型感知模式 + `--deny-warnings`，即 **warning 也判失败**                                                                                     |
+| 类型 | `bun run typecheck`  | `--strict` 以及 `noUncheckedIndexedAccess`、`exactOptionalPropertyTypes`、`verbatimModuleSyntax`，这正是保证每个文件无需转译就能被 pi 直接加载的原因 |
+| 文档 | `bun run docs:check` | 每个 `README.md` 都有 `README_CN.md`，标题层级序列一致且语言切换链接可用                                                                             |
+| 单测 | `bun test`           | `extensions/*/` 下的单元测试                                                                                                                         |
+
+提交遵循 [Conventional Commits](https://www.conventionalcommits.org/)：`commit-msg` 钩子会拒绝不符合
+`type(scope): summary` 的标题，pre-commit 钩子只对暂存文件做格式化与 lint。工具链在 `package.json`
+中锁定精确版本（`bunfig.toml` 设了 `install.exact = true`）。`@earendil-works/*` 刻意保留为 `*`：
+它们是 pi 提供的宿主 API，跟随它才能尽早发现上游变更。
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。

package/extensions/statusline/README.md

@@ -0,0 +1,87 @@
+# statusline
+
+English | [中文](README_CN.md)
+
+Replaces pi's footer with a labelled two-row one. Every value carries a word, so nothing has to be
+decoded from a symbol or remembered from a legend.
+
+```
+Context  █████████▍░░░░░░░░░░  47.1%   471k / 1.0M          Cache 38M · Hit 100.0% · Cost $0.56
+~/.pi (master)              deepseek-flash · Effort high · TTFT 482ms · 729 tok/s
+LSP Active: typescript
+```
+
+## What each part is
+
+| Part                        | Meaning                                                                                                                                                                                      |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Context` + meter + `47.1%` | Share of the model's context window in use. The fill turns `warning` above 70% and `error` above 90%, the same thresholds pi's shipped footer uses, and the percentage changes color with it |
+| `471k / 1.0M`               | Absolute context tokens over the window size. Dropped first when the terminal is narrow                                                                                                      |
+| `Cache` / `Hit` / `Cost`    | Cumulative prompt-cache reads, the latest turn's cache hit rate (`cacheRead / (input + cacheRead + cacheWrite)`), and session cost                                                           |
+| Effort                      | The active thinking level                                                                                                                                                                    |
+| `TTFT`                      | Time from request dispatch to the first streamed token                                                                                                                                       |
+| `tok/s`                     | Decode throughput, i.e. output tokens per second of decode time                                                                                                                              |
+| Last line                   | Other extensions' `ctx.ui.setStatus()` entries, so they do not silently disappear                                                                                                            |
+
+## The meter
+
+The meter is a **fixed 20 cells** and never stretches to the terminal. That is the one structural rule
+taken from [cli-progress](https://www.npmjs.com/package/cli-progress)'s `shades_classic` preset
+(≈10M downloads/week): its bar has a fixed `barsize` and is never widened to fill the row. An earlier
+revision here did stretch it, which made the meter read as chrome rather than as an instrument.
+
+The glyphs are that preset's block fill and shaded block track, with a 1/8-cell leading edge
+(`▏▎▍▌▋▊▉`) so the fill grows smoothly instead of jumping a whole cell at a time.
+
+Configuration lives at the top of [`render.ts`](render.ts):
+
+| Constant       | Default | Notes                                                                             |
+| -------------- | ------- | --------------------------------------------------------------------------------- |
+| `BAR_CELLS`    | `20`    | Meter width. Narrower for a quieter footer, wider for more resolution             |
+| `BAR_FILL`     | `█`     | Fill glyph                                                                        |
+| `BAR_TRACK`    | `░`     | Set to `""` for a trackless meter, or `"─"` for a hairline one                    |
+| `QUIET_STATUS` | pi-lens | `[statusKey, pattern]` pairs whose matching text is hidden as "nothing to report" |
+
+## Metrics
+
+Throughput and latency follow the
+[deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) turn-metrics contract
+(`packages/client/ui-chat/src/client/contract/turn-metrics.ts`), including its number formatting:
+
+```
+ttftMs   = firstTokenTime - stepStartTime
+decodeMs = completedTime  - firstTokenTime
+tok/s    = usage.output / (decodeMs / 1000)
+```
+
+So the rate excludes prefill and time-to-first-token, which is the industry-standard
+"output tokens per second" figure.
+
+- **Final values are exact.** They use the provider's reported `usage.output` over the measured
+  decode window.
+- **Live values are estimates**, marked with `~`. Providers report usage only on the final stream
+  chunk, so the streaming token count is inferred from streamed characters scaled by a
+  tokens-per-character ratio learned from this session's own reported usage.
+- **TTFT is exact as soon as the first token arrives** and never changes for that turn.
+- The reading appears after the first turn completes in the session, because it can only come from
+  streamed events.
+
+## Requirements and limits
+
+- One extension owns the footer. `ctx.ui.setFooter()` is exclusive, so installing another footer
+  extension alongside this one is a race, not a merge. This extension stands down if
+  [pi-fancy-footer](https://github.com/mavam/pi-fancy-footer) announces itself, so the two coexist
+  without fighting.
+- The footer renders on `ctx.sessionManager.getEntries()` and `ctx.getContextUsage()`, both public
+  API; nothing reaches into pi's internals.
+- Provider status such as `MCP: 2 servers enabled` is informational and can be turned off at its
+  source: `settings.mcpFooterStatus` in `~/.pi/agent/mcp.json`. `LSP Inactive` from pi-lens has no
+  such setting, so it is filtered here as a "quiet" status.
+
+## Install
+
+```sh
+pi install git:github.com/reedchan7/useful-pi-extensions
+```
+
+Then `/reload`.

package/extensions/statusline/README_CN.md

@@ -0,0 +1,77 @@
+# statusline
+
+[English](README.md) | 中文
+
+替换 pi 的 footer，改成带文字标签的两行。每个值都带一个词，不需要靠符号猜、也不需要记图例。
+
+```
+Context  █████████▍░░░░░░░░░░  47.1%   471k / 1.0M          Cache 38M · Hit 100.0% · Cost $0.56
+~/.pi (master)              deepseek-flash · Effort high · TTFT 482ms · 729 tok/s
+LSP Active: typescript
+```
+
+## 每一项是什么
+
+| 部分                       | 含义                                                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `Context` + 仪表 + `47.1%` | 已占模型上下文窗口的比例。填充超过 70% 转 `warning`、超过 90% 转 `error`（与 pi 原生 footer 同一套阈值），百分比同步变色 |
+| `471k / 1.0M`              | 上下文已用 token / 窗口大小。终端变窄时**优先丢弃**这一项                                                                |
+| `Cache` / `Hit` / `Cost`   | 累计 prompt cache 读取量、最近一轮缓存命中率（`cacheRead / (input + cacheRead + cacheWrite)`）、会话花费                 |
+| Effort                     | 当前思考等级                                                                                                             |
+| `TTFT`                     | 从发出请求到第一个流式 token 的耗时                                                                                      |
+| `tok/s`                    | 解码吞吐，即每秒解码时间产出的输出 token 数                                                                              |
+| 最后一行                   | 其他扩展通过 `ctx.ui.setStatus()` 设的状态，否则它们会静默消失                                                           |
+
+## 关于这个仪表
+
+仪表**固定 20 格，永不拉伸到终端宽度**。这是从 [cli-progress](https://www.npmjs.com/package/cli-progress)
+的 `shades_classic` 预设（约 1000 万次/周下载）里抄来的唯一一条结构性规则：它的进度条有固定 `barsize`，
+永远不会被撑满整行。之前的版本正是撑满了整行，于是它读起来像"装饰线"而不是"仪表"。
+
+字形也来自那个预设（实心块填充 + 阴影块轨道），额外加了 1/8 格收尾（`▏▎▍▌▋▊▉`），
+让填充平滑增长，而不是一次跳一整格。
+
+可调项在 [`render.ts`](render.ts) 顶部：
+
+| 常量           | 默认值  | 说明                                                    |
+| -------------- | ------- | ------------------------------------------------------- |
+| `BAR_CELLS`    | `20`    | 仪表宽度。想更安静就调窄，想要更高分辨率就调宽          |
+| `BAR_FILL`     | `█`     | 填充字形                                                |
+| `BAR_TRACK`    | `░`     | 设为 `""` 得到无轨道仪表，设为 `"─"` 得到细线轨道       |
+| `QUIET_STATUS` | pi-lens | `[状态键, 正则]` 列表，匹配到的文本视为"无事发生"而隐藏 |
+
+## 指标口径
+
+吞吐与延迟遵循 [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) 的 turn-metrics 契约
+（`packages/client/ui-chat/src/client/contract/turn-metrics.ts`），数字格式也照抄：
+
+```
+ttftMs   = firstTokenTime - stepStartTime
+decodeMs = completedTime  - firstTokenTime
+tok/s    = usage.output / (decodeMs / 1000)
+```
+
+所以速率**不含 prefill 和首 token 延迟**，这是业界标准的"输出 token/秒"。
+
+- **回合结束后是精确值**：用 provider 上报的 `usage.output` 除以实测解码窗口。
+- **流式期间是估算值**，前面带 `~`。provider 只在最后一个流式分片才回 usage，所以流式期间的 token 数
+  由已流出字符数乘以"每字符 token 比"推断，该比值从本会话自己上报的 usage 学到。
+- **TTFT 在首个 token 到达时就精确**，那一轮内不再变化。
+- 读数在会话中**第一轮结束后**才出现，因为它只能来自流式事件。
+
+## 要求与限制
+
+- footer 只能有一个扩展占用。`ctx.ui.setFooter()` 是排他的，所以再装一个 footer 扩展是**竞争**而不是叠加。
+  本扩展在检测到 [pi-fancy-footer](https://github.com/mavam/pi-fancy-footer) 时会主动让位，两者不会互相打架。
+- footer 只读取 `ctx.sessionManager.getEntries()` 和 `ctx.getContextUsage()`，都是公开 API，
+  没有触碰 pi 内部实现。
+- `MCP: 2 servers enabled` 这类信息性状态可以在源头关掉：`~/.pi/agent/mcp.json` 的
+  `settings.mcpFooterStatus`。pi-lens 的 `LSP Inactive` 没有类似开关，所以在本地按"安静状态"过滤。
+
+## 安装
+
+```sh
+pi install git:github.com/reedchan7/useful-pi-extensions
+```
+
+然后 `/reload`。

package/extensions/statusline/index.ts

@@ -0,0 +1,331 @@
+/**
+ * Status line extension — replaces pi's footer with a labelled two-row one.
+ *
+ * See README.md for the rendered layout and what each part means.
+ *
+ * Design notes:
+ *
+ * - Every value carries a word ("Context", "Cache", "Cost", "Effort"), not a symbol: icon-only labels
+ *   are unreadable at a glance.
+ * - Keys render dim and values render brighter, so a key/value pair reads as one unit instead of as a
+ *   run of equal-weight tokens.
+ * - The meter is a FIXED 20 cells and never stretches to the terminal, so it reads as an instrument
+ *   instead of as chrome. render.ts records where the idiom is from.
+ * - Other extensions' ctx.ui.setStatus() entries are still rendered, or they would silently disappear
+ *   from the footer.
+ *
+ * Throughput follows the deepseek-harness turn-metrics contract: ttftMs = firstTokenTime -
+ * stepStartTime; decodeMs = completedTime - firstTokenTime; tok/s = usage.output / (decodeMs / 1000)
+ */
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ReadonlyFooterDataProvider,
+} from '@earendil-works/pi-coding-agent'
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui'
+
+import {
+  bar,
+  BAR_CELLS,
+  formatCost,
+  formatCwd,
+  formatLatency,
+  formatTokens,
+  formatTps,
+  isQuietStatus,
+  pair,
+  percentColor,
+  row,
+  shortenPath,
+} from './render.ts'
+
+const LIVE_RENDER_MS = 200
+const WINDOW_MS = 2000
+const MIN_SAMPLE_MS = 200
+/** Pi's own estimateTokens() heuristic, used only until a real ratio is known. */
+const FALLBACK_TOKENS_PER_CHAR = 0.25
+
+/** A content block as providers stream it; every field is read defensively. */
+type ContentBlock = {
+  type?: unknown
+  text?: unknown
+  thinking?: unknown
+  name?: unknown
+  arguments?: unknown
+}
+
+function isContentBlock(value: unknown): value is ContentBlock {
+  return typeof value === 'object' && value !== null
+}
+
+function blockChars(content: unknown): number {
+  if (typeof content === 'string') return content.length
+  if (!Array.isArray(content)) return 0
+
+  let chars = 0
+  for (const raw of content as unknown[]) {
+    if (!isContentBlock(raw)) continue
+    const { type, text, thinking, name, arguments: args } = raw
+    if (type === 'text' && typeof text === 'string') chars += text.length
+    else if (type === 'thinking' && typeof thinking === 'string') chars += thinking.length
+    else if (type === 'toolCall') {
+      const nameLength = typeof name === 'string' ? name.length : 0
+      chars += nameLength + JSON.stringify(args ?? {}).length
+    }
+  }
+  return chars
+}
+
+interface Totals {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  cost: number
+  cacheHitRate: number | null
+}
+
+/** The usage fields this footer totals, read structurally so no cast is needed. */
+type UsageTotals = {
+  input: number
+  output: number
+  cacheRead: number
+  cacheWrite: number
+  cost: { total: number }
+}
+
+function collectTotals(ctx: ExtensionContext): Totals {
+  const totals: Totals = {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    cost: 0,
+    cacheHitRate: null,
+  }
+  // `usage` stays optional here even though an assistant message always carries it:
+  // a truncated or hand-edited session file is the case this guard is for.
+  const add = (usage: UsageTotals | undefined, assistant: boolean): void => {
+    if (!usage) return
+    totals.input += usage.input
+    totals.output += usage.output
+    totals.cacheRead += usage.cacheRead
+    totals.cacheWrite += usage.cacheWrite
+    totals.cost += usage.cost.total
+    if (!assistant) return
+    const prompt = usage.input + usage.cacheRead + usage.cacheWrite
+    if (prompt > 0) totals.cacheHitRate = (usage.cacheRead / prompt) * 100
+  }
+  for (const entry of ctx.sessionManager.getEntries()) {
+    if (entry.type === 'message') {
+      const { message } = entry
+      if (message.role === 'assistant') add(message.usage, true)
+      else if (message.role === 'toolResult') add(message.usage, false)
+      continue
+    }
+    // Compaction and branch summaries bill a model call of their own.
+    if (entry.type === 'compaction' || entry.type === 'branch_summary') add(entry.usage, false)
+  }
+  return totals
+}
+
+/** Tokens per character, averaged over recent assistant messages with provider usage. */
+function seedRatio(ctx: ExtensionContext): number | null {
+  const samples: number[] = []
+  for (const entry of ctx.sessionManager.getBranch().toReversed()) {
+    if (entry.type !== 'message' || entry.message.role !== 'assistant') continue
+    const output = entry.message.usage.output
+    const chars = blockChars(entry.message.content)
+    if (output <= 0 || chars <= 0) continue
+    samples.push(output / chars)
+    if (samples.length >= 5) break
+  }
+  if (samples.length === 0) return null
+  return samples.reduce((sum, value) => sum + value, 0) / samples.length
+}
+
+export default function (pi: ExtensionAPI) {
+  let ratio: number | null = null
+  let requestRender: (() => void) | null = null
+
+  // Latest turn reading: { rate, exact, ttftMs }
+  let reading: { rate: number; exact: boolean; ttftMs: number | null } | null = null
+
+  let chars = 0
+  let stepStartedAt = 0
+  let firstTokenAt: number | null = null
+  let windowAt = 0
+  let windowTokens = 0
+  let renderedAt = 0
+
+  function resetStream(): void {
+    chars = 0
+    firstTokenAt = null
+    windowAt = 0
+    windowTokens = 0
+    renderedAt = 0
+  }
+
+  function publish(rate: number, exact: boolean, ttftMs: number | null): void {
+    reading = { rate, exact, ttftMs }
+    requestRender?.()
+  }
+
+  function installFooter(ctx: ExtensionContext): void {
+    ctx.ui.setFooter((tui, theme, footerData: ReadonlyFooterDataProvider) => {
+      requestRender = () => tui.requestRender()
+
+      return {
+        invalidate() {},
+        dispose() {
+          requestRender = null
+        },
+        render(width: number): string[] {
+          const usage = ctx.getContextUsage()
+          const totals = collectTotals(ctx)
+          const percent = usage?.percent ?? null
+          const fraction = percent === null ? 0 : percent / 100
+
+          // Row 1 right: cache and cost, words instead of symbols.
+          const row1Parts: string[] = []
+          if (totals.cacheRead > 0)
+            row1Parts.push(pair(theme, 'Cache', formatTokens(totals.cacheRead)))
+          if (totals.cacheHitRate !== null) {
+            row1Parts.push(pair(theme, 'Hit', `${totals.cacheHitRate.toFixed(1)}%`))
+          }
+          if (totals.cost > 0) row1Parts.push(pair(theme, 'Cost', formatCost(totals.cost)))
+          const row1Right = row1Parts.join(theme.fg('dim', '  ·  '))
+
+          // Row 1 left: fixed-size meter, percentage as the hero, absolute figures
+          // as quiet secondary detail. Air to the right of the meter is deliberate.
+          const pctColor = percentColor(percent)
+          const pctText = theme.fg(pctColor, percent === null ? '?' : `${percent.toFixed(1)}%`)
+          const window = usage?.contextWindow ?? ctx.model?.contextWindow ?? 0
+          const detail =
+            window > 0 ? `${formatTokens(usage?.tokens ?? 0)} / ${formatTokens(window)}` : ''
+          const meter = `${theme.fg('dim', 'Context')}  ${bar(theme, BAR_CELLS, fraction)}  ${pctText}`
+          const withDetail = detail ? `${meter}   ${theme.fg('dim', detail)}` : meter
+          // Shed the secondary detail before the cache/cost group gets squeezed.
+          const row1Left =
+            visibleWidth(withDetail) + 2 + visibleWidth(row1Right) <= width ? withDetail : meter
+
+          // Row 2: model and the latest turn's timing on the right, path on the left.
+          const model = ctx.model?.id ?? 'no model'
+          const row2Parts = [theme.fg('accent', model)]
+          if (ctx.thinkingLevel) row2Parts.push(pair(theme, 'Effort', ctx.thinkingLevel, 'muted'))
+          if (reading) {
+            if (reading.ttftMs !== null)
+              row2Parts.push(pair(theme, 'TTFT', formatLatency(reading.ttftMs), 'muted'))
+            row2Parts.push(
+              theme.fg(
+                reading.exact ? 'success' : 'dim',
+                `${reading.exact ? '' : '~'}${formatTps(reading.rate)} tok/s`,
+              ),
+            )
+          }
+          const row2Right = row2Parts.join(theme.fg('dim', '  ·  '))
+
+          const branch = footerData.getGitBranch()
+          const path = formatCwd(ctx.cwd)
+          const branchSuffix = branch ? ` (${branch})` : ''
+          // The model and the live reading matter more than the full path.
+          const rightW2 = visibleWidth(row2Right)
+          const room = width - rightW2 - 2
+          let pwdPlain = ''
+          if (room >= 10) {
+            if (path.length + branchSuffix.length <= room) {
+              pwdPlain = path + branchSuffix
+            } else {
+              // Shorten the path first; drop the branch only if it still will not fit.
+              const withBranch =
+                shortenPath(path, Math.max(1, room - branchSuffix.length)) + branchSuffix
+              pwdPlain = withBranch.length <= room ? withBranch : shortenPath(path, room)
+            }
+          }
+          const row2Left = pwdPlain ? theme.fg('muted', pwdPlain) : ''
+
+          const lines = [
+            row(theme, width, row1Left, row1Right),
+            row(theme, width, row2Left, row2Right),
+          ]
+
+          // Other extensions' status entries still belong on screen, minus the
+          // ones that only report that nothing is happening.
+          const visibleStatuses = [...footerData.getExtensionStatuses().entries()]
+            .filter(([key, value]) => !isQuietStatus(key, value))
+            .toSorted(([a], [b]) => a.localeCompare(b))
+            .map(([, value]) => value.replace(/[\r\n\t]+/g, ' ').trim())
+            .join('  ')
+          if (visibleStatuses)
+            lines.push(truncateToWidth(visibleStatuses, width, theme.fg('dim', '...')))
+          return lines
+        },
+      }
+    })
+  }
+
+  pi.on('session_start', async (_event, ctx) => {
+    ratio = seedRatio(ctx)
+    reading = null
+    resetStream()
+    installFooter(ctx)
+  })
+
+  pi.on('message_start', async (event) => {
+    if (event.message.role !== 'assistant') return
+    resetStream()
+    stepStartedAt = Date.now()
+  })
+
+  pi.on('message_update', async (event) => {
+    const delta = event.assistantMessageEvent
+    // Narrowing on the discriminant is what keeps the payload typed; membership in
+    // a Set of strings tells the compiler nothing.
+    if (
+      delta.type !== 'text_delta' &&
+      delta.type !== 'thinking_delta' &&
+      delta.type !== 'toolcall_delta'
+    ) {
+      return
+    }
+
+    const now = Date.now()
+    if (firstTokenAt === null) firstTokenAt = now
+    chars += delta.delta.length
+
+    const tokens = chars * (ratio ?? FALLBACK_TOKENS_PER_CHAR)
+    if (windowAt === 0 || now - windowAt > WINDOW_MS) {
+      windowAt = now
+      windowTokens = tokens
+    }
+
+    const decodeMs = now - firstTokenAt
+    if (decodeMs < MIN_SAMPLE_MS || now - renderedAt < LIVE_RENDER_MS) return
+
+    const windowMs = now - windowAt
+    const rate =
+      windowMs > 0 ? ((tokens - windowTokens) / windowMs) * 1000 : (tokens / decodeMs) * 1000
+    renderedAt = now
+    publish(rate, false, firstTokenAt - stepStartedAt)
+  })
+
+  pi.on('message_end', async (event) => {
+    if (event.message.role !== 'assistant') return
+
+    const message = event.message as { content: unknown; usage?: { output?: number } }
+    const output = message.usage?.output ?? 0
+    const totalChars = blockChars(message.content)
+    if (output > 0 && totalChars > 0) {
+      const sample = output / totalChars
+      ratio = ratio === null ? sample : (ratio + sample) / 2
+    }
+
+    const decodeMs = firstTokenAt !== null ? Date.now() - firstTokenAt : 0
+    const ttftMs = firstTokenAt !== null ? firstTokenAt - stepStartedAt : null
+    const tokens = output > 0 ? output : totalChars * (ratio ?? FALLBACK_TOKENS_PER_CHAR)
+    if (ttftMs !== null && decodeMs >= MIN_SAMPLE_MS)
+      publish((tokens / decodeMs) * 1000, output > 0, ttftMs)
+    resetStream()
+  })
+}

package/extensions/statusline/render.ts

@@ -0,0 +1,157 @@
+/**
+ * Pure rendering helpers for the status line: number formatting, the context meter, the two-group
+ * row layout, and the status-noise filter.
+ *
+ * Nothing here touches pi APIs, the filesystem, or the clock, so every export is a function of its
+ * arguments alone and is covered by render.test.ts.
+ */
+
+import { homedir } from 'node:os'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+
+import type { Theme, ThemeColor } from '@earendil-works/pi-coding-agent'
+import { truncateToWidth, visibleWidth } from '@earendil-works/pi-tui'
+
+/**
+ * Meter geometry, copied from cli-progress's `shades_classic` preset (10M downloads/week): block
+ * fill, shaded block track. Its one structural rule is that the bar is a FIXED width (`barsize`,
+ * default 40) and never stretches to the row. An earlier revision here stretched it to the
+ * terminal, which is what made it read as chrome rather than as an instrument. 20 cells is the
+ * footer-sized equivalent.
+ */
+export const BAR_CELLS = 20
+export const BAR_FILL = '█'
+/**
+ * Set to '' for a trackless bar, or '─' for a hairline track. Annotated `string` rather than left
+ * as its literal type, so the empty case below is a real branch.
+ */
+export const BAR_TRACK: string = '░'
+
+/** 1/8-cell fill ladder (U+258F..U+2588) for a smooth leading edge. */
+const EIGHTHS = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉']
+
+/** Strip ANSI so status text can be pattern-matched on its visible form. */
+// eslint-disable-next-line no-control-regex -- matching an ANSI escape requires the ESC character
+export const ANSI = /\u001b\[[0-9;]*m/g
+
+/**
+ * Status entries that only report that nothing is happening. Other extensions set these
+ * persistently; they cost a row without carrying information. Matching is keyed by status key, so
+ * an unrelated extension that happens to use the same words is left alone.
+ */
+export const QUIET_STATUS: ReadonlyArray<readonly [string, RegExp]> = [
+  ['pi-lens-lsp', /^LSP Inactive$/i],
+]
+
+export function formatTokens(count: number): string {
+  if (count < 1000) return String(count)
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`
+  if (count < 1000000) return `${Math.round(count / 1000)}k`
+  if (count < 10000000) return `${(count / 1000000).toFixed(1)}M`
+  return `${Math.round(count / 1000000)}M`
+}
+
+/** Whole tokens from ten up, one decimal below (matches the harness formatter). */
+export function formatTps(tps: number): string {
+  const clamped = Math.max(0, tps)
+  return clamped >= 10 ? String(Math.round(clamped)) : String(Math.round(clamped * 10) / 10)
+}
+
+/** Milliseconds below a second, seconds with one decimal under ten, whole seconds from there. */
+export function formatLatency(ms: number): string {
+  const clamped = Math.max(0, ms)
+  if (clamped < 1000) return `${Math.round(clamped)}ms`
+  const seconds = clamped / 1000
+  return `${seconds < 10 ? Math.round(seconds * 10) / 10 : Math.round(seconds)}s`
+}
+
+/** Home-relative path, or the absolute path when it is outside the home directory. */
+export function formatCwd(cwd: string): string {
+  const home = homedir()
+  if (!home) return cwd
+  try {
+    const rel = relative(resolve(home), resolve(cwd))
+    const inside = rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+    if (!inside) return cwd
+    return rel === '' ? '~' : `~${sep}${rel}`
+  } catch {
+    return cwd
+  }
+}
+
+/** Three decimals, with one trailing zero trimmed so `$0.380` renders as `$0.38`. */
+export function formatCost(cost: number): string {
+  return `$${cost.toFixed(3).replace(/0$/, '')}`
+}
+
+/**
+ * Shorten a path from the left, keeping the tail that identifies the project. Never returns a
+ * mid-word fragment: it degrades to `…/last` and then to `last…`.
+ */
+export function shortenPath(path: string, maxWidth: number): string {
+  if (path.length <= maxWidth) return path
+  const parts = path.split(sep).filter(Boolean)
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const candidate = `…${sep}${parts.slice(i).join(sep)}`
+    if (candidate.length <= maxWidth) return candidate
+  }
+  const tail = parts.at(-1) ?? path
+  return tail.length <= maxWidth ? tail : `${tail.slice(0, Math.max(1, maxWidth - 1))}…`
+}
+
+/** Context pressure: accent is healthy, warning starts above 70%, error above 90%. */
+export function barColor(fraction: number): ThemeColor {
+  if (fraction > 0.9) return 'error'
+  if (fraction > 0.7) return 'warning'
+  return 'accent'
+}
+
+/** The same thresholds applied to the printed percentage. */
+export function percentColor(percent: number | null): ThemeColor {
+  if (percent === null) return 'text'
+  if (percent > 90) return 'error'
+  if (percent > 70) return 'warning'
+  return 'text'
+}
+
+/**
+ * Cli-progress's bar algorithm (`shades_classic`), plus a 1/8-cell leading edge so the fill grows
+ * smoothly instead of jumping a whole cell at a time.
+ */
+export function bar(theme: Theme, cells: number, fraction: number): string {
+  const clamped = Math.max(0, Math.min(1, fraction))
+  const scaled = clamped * cells
+  const whole = Math.min(cells, Math.floor(scaled))
+  const edge = whole < cells ? (EIGHTHS[Math.floor((scaled - whole) * 8)] ?? '') : ''
+  const fill = theme.fg(barColor(clamped), BAR_FILL.repeat(whole) + edge)
+  if (!BAR_TRACK) return fill
+  return fill + theme.fg('dim', BAR_TRACK.repeat(Math.max(0, cells - whole - edge.length)))
+}
+
+/**
+ * Left group and right group on one line, padded to `width`. When the two do not fit, the right
+ * group is dropped rather than half rendered, so no number ever appears cut; the wider side keeps
+ * the line when only one of them fits.
+ */
+export function row(theme: Theme, width: number, left: string, right: string): string {
+  const leftWidth = visibleWidth(left)
+  const rightWidth = right ? visibleWidth(right) : 0
+  const gap = leftWidth > 0 && rightWidth > 0 ? 2 : 0
+  if (rightWidth > 0 && leftWidth + gap + rightWidth <= width) {
+    return left + ' '.repeat(Math.max(0, width - leftWidth - rightWidth)) + right
+  }
+  const keep = leftWidth > 0 ? left : right
+  return truncateToWidth(keep, width, theme.fg('dim', '…'))
+}
+
+/** `label value` where the key is quiet and the value is not. */
+export function pair(theme: Theme, key: string, value: string, color: ThemeColor = 'text'): string {
+  return `${theme.fg('dim', key)} ${theme.fg(color, value)}`
+}
+
+/** True when a status entry only reports that nothing is happening. */
+export function isQuietStatus(key: string, value: unknown): boolean {
+  const rule = QUIET_STATUS.find(([candidate]) => candidate === key)
+  if (!rule) return false
+  return rule[1].test(String(value).replace(ANSI, '').trim())
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "useful-pi-extensions",
+  "version": "0.1.0",
+  "description": "A small collection of pi extensions, installed with one command — a labelled status line with context pressure, cache, cost, effort, TTFT and tokens/sec.",
+  "keywords": [
+    "bun",
+    "cli",
+    "footer",
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "statusline",
+    "terminal",
+    "tui",
+    "typescript"
+  ],
+  "homepage": "https://github.com/reedchan7/useful-pi-extensions#readme",
+  "bugs": {
+    "url": "https://github.com/reedchan7/useful-pi-extensions/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reedchan7/useful-pi-extensions.git"
+  },
+  "files": [
+    "extensions",
+    "!extensions/**/*.test.ts",
+    "README.md",
+    "README_CN.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "scripts": {
+    "check": "bun run fmt:check && bun run lint && bun run typecheck && bun run docs:check && bun run test",
+    "docs:check": "bun tools/check-docs-pairing/src/index.ts",
+    "fmt": "oxfmt --write .",
+    "fmt:check": "oxfmt --check .",
+    "lint": "oxlint --deny-warnings .",
+    "lint:fix": "oxlint --fix .",
+    "prepublishOnly": "bun run check",
+    "test": "bun test",
+    "test:changed": "git rev-parse --verify --quiet origin/main >/dev/null && bun test --changed=origin/main || bun test",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@types/bun": "1.4.2",
+    "lefthook": "2.1.14",
+    "oxfmt": "0.68.0",
+    "oxlint": "1.83.0",
+    "oxlint-tsgolint": "7.0.2002",
+    "typescript": "7.0.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "image": "https://github.com/user-attachments/assets/7ae64213-cb05-4440-835e-a633796a87f9"
+  }
+}