rinco-pi-hud 1.0.0 → 1.1.1

package/README.md

@@ -12,17 +12,18 @@
 
 </div>
 
-Rinco Pi HUD provides a rich, real-time status footer for Pi TUI sessions. It displays project state, Git metrics, runtime versions, session activity, model usage, token costs, and more — all in a configurable three-line or single-line layout. Pi loads the TypeScript extension directly, so no build step is required (`tsconfig.json` sets `noEmit: true` and is used only for `npm run typecheck`).
+Rinco Pi HUD provides a rich, real-time status footer for Pi TUI sessions. It displays project state, Git metrics, runtime versions, session activity, model usage, token costs, and more — all in a responsive four-group or customizable single-line layout. Pi loads the TypeScript extension directly, so no build step is required (`tsconfig.json` sets `noEmit: true` and is used only for `npm run typecheck`).
 
 ## Features
 
-- **Project state** — Working directory, Git branch, commit, tag, status, diff metrics, and runtime versions.
-- **Session activity** — Model, provider, context usage, tokens, cache, session cost, turn count, and thinking level.
-- **Tool and agent activity** — Native tool completion counts, running tools, active agent runs, skills, and MCP server status.
+- **Project state** — Working directory, Git branch, commit, tag, status, operation state, diff metrics, and runtime versions.
+- **Session activity** — Model, provider, context usage, independently controlled input/output tokens, cache, session cost, turn count, and thinking level.
+- **Tool and agent activity** — Independent controls for running tools, completed tool counts, active agents, idle state, skills, and MCP server status.
 - **Model quota** — Automatic Codex weekly quota or Token Switch balance display by model provider.
 - **Git awareness** — Branches, detached HEAD, tags, ahead/behind, stash, merge/rebase conflicts, and dirty state.
 - **Runtime detection** — Node, Python, Go, Rust, Java, and 60+ other runtimes with package version parsing.
-- **Configurable layout** — Three-line categorized layout by default, or fully customizable single-line templates.
+- **Configurable layout** — Responsive Project, Session, Activity, and Usage groups by default, or fully customizable single-line templates.
+- **Granular status controls** — Toggle Git operation state, tool runtime/counts, active/idle agents, and input/output tokens separately from `/zentui`.
 - **Extension statuses** — Reads third-party extension statuses and places them by configurable position and color mode.
 - **Safe fallback** — Graceful timeout and error handling; no stale data after session shutdown.
 
@@ -69,6 +70,10 @@ The HUD footer is enabled by default. Run `/zentui` to open the interactive sett
 /zentui statusline enable
 /zentui statusline disable
 /zentui statusline toggle
+/zentui row project toggle
+/zentui row session disable
+/zentui row activity enable
+/zentui row usage toggle
 /zentui format clear
 /zentui format "$model · $context · $cost · $git_branch( $git_commit) · $session_duration"
 /codex-status
@@ -82,24 +87,24 @@ The HUD footer is enabled by default. Run `/zentui` to open the interactive sett
 
 | Path | Purpose |
 | --- | --- |
-| [`extensions/hud/index.ts`](extensions/hud/index.ts) | Extension lifecycle and side-effect orchestration |
-| [`extensions/hud/config/`](extensions/hud/config/config.ts) | Configuration model, normalization, and persistence |
-| [`extensions/hud/footer/`](extensions/hud/footer/index.ts) | Footer rendering, categorized layout, and template parsing |
+| [`extensions/hud/index.ts`](extensions/hud/index.ts) | Composition root for controllers, shared state, and UI installation |
+| [`extensions/hud/config/`](extensions/hud/config/config.ts) | Configuration model, normalization, migration, and persistence |
+| [`extensions/hud/footer/`](extensions/hud/footer/index.ts) | Footer rendering, semantic grouping, responsive layout, and template parsing |
 | [`extensions/hud/segments/`](extensions/hud/segments/) | State collectors: Git, runtime, MCP, skills, projects, etc. |
 | [`extensions/hud/telemetry/`](extensions/hud/telemetry/format.ts) | Usage formatting, token switch, and Codex subscription client |
-| [`extensions/hud/session/`](extensions/hud/session/) | Session lifecycle, context, and live context overlay |
-| [`extensions/hud/state/`](extensions/hud/state/) | Aggregated state, telemetry, and project refresh |
-| [`extensions/hud/commands/`](extensions/hud/commands/settings.ts) | `/zentui` command and interactive TUI settings |
+| [`extensions/hud/session/`](extensions/hud/session/) | Pi event registration, session lifecycle, and live context overlay |
+| [`extensions/hud/state/`](extensions/hud/state/) | Aggregated state, telemetry reducer, and project refresh controller |
+| [`extensions/hud/commands/`](extensions/hud/commands/settings.ts) | `/zentui` settings UI and configuration controller |
 | [`extensions/hud/ui/`](extensions/hud/ui/) | Icons and terminal style utilities |
 | [`docs/footer.md`](docs/footer.md) | Complete footer configuration reference |
 | [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) | Local development, testing guidance, and pull request checklist |
-| [`tests/`](tests/) | Vitest test suite (34+ tests across 6 files) |
+| [`tests/`](tests/) | Vitest test suite (41 tests across 8 files) |
 
 ## Customization
 
 ### Layout
 
-The default three-line layout groups project, session, and usage information. Set `footerFormat` to a template string for a single-line layout:
+The default layout groups Project, Session, Activity, and Usage information. Long groups wrap at complete segment boundaries with aligned continuation lines. Set `footerFormat` to a template string for a single-line layout:
 
 ```text
 /zentui format "$cwd( $git_branch)$fill($context)( $tokens)( $cost)"
@@ -109,14 +114,25 @@ Template variables use `$name` or `${name}` syntax. See the [footer reference](d
 
 ### Segments
 
-Enable or disable individual status segments via `/zentui`:
+Open `/zentui`, then select **Built-in segments** to enable or disable individual statuses. Fine-grained controls include:
+
+| Group | Independently controlled statuses |
+| --- | --- |
+| Project | Git status, Git operation state (`MERGING`, `REBASING`, etc.), commit, metrics, runtime, package, OS, and user |
+| Session | Model, thinking level, turn count, and duration |
+| Activity | Running tools, completed tool counts, active agents, `Agent idle`, skills, and MCP |
+| Usage | Context, input tokens, output tokens, cache details/hit rate, cost, quota, and time |
+
+Existing configs using the former aggregate `tokens`, `toolActivity`, or `agentActivity` switches are migrated automatically. The whole footer can still be controlled with `/zentui statusline enable|disable|toggle`.
+
+In the default four-row layout, each semantic row can also be controlled directly:
 
 ```text
-/zentui statusline enable
-/zentui statusline disable
-/zentui statusline toggle
+/zentui row <project|session|activity|usage> <enable|disable|toggle>
 ```
 
+Row switches are persisted in `footerRows`. They do not affect a custom single-line `footerFormat`.
+
 ### Extension statuses
 
 Third-party extensions publish statuses that the HUD footer can display. Configure placement (`left`, `middle`, `right`, `off`) and color mode (`zentui`, `original`) for each extension status key.
@@ -160,11 +176,10 @@ Check types:
 npm run typecheck
 ```
 
-Verify tests and package contents:
+Verify formatting, types, lint rules, tests, and package contents:
 
 ```bash
-npm test
-npm run typecheck
+npm run verify
 npm run pack:check
 ```
 

package/docs/CONTRIBUTING.md

@@ -39,16 +39,20 @@ Pi loads the TypeScript extension directly, so this project has no separate buil
 Before submitting a change, run:
 
 ```bash
-npm test
-npm run typecheck
+npm run verify
 npm run pack:check
 ```
 
+`npm run verify` checks Prettier formatting, TypeScript types, ESLint rules, and the Vitest suite.
+
 Tests live in `tests/`:
 
 - `zentui-status.test.ts` — Config counts, MCP status parsing, and extension status helpers.
 - `codex-usage.test.ts` — Codex payload normalization and model-specific quota formatting.
-- `footer-layout.test.ts` — Categorized three-line layout and narrow-width budget.
+- `footer-layout.test.ts` — Four-group categorized layout, segment wrapping, and narrow-width budget.
+- `footer-groups.test.ts` — Semantic Project, Session, Activity, and Usage segment ordering.
+- `footer-segment-controls.test.ts` — Independent status controls and legacy-config migration.
+- `footer-row-controls.test.ts` — Per-row command parsing, persistence, and configuration defaults.
 - `model-switch-statusline.test.ts` — Model switch statusline integration.
 - `model-usage-refresh.test.ts` — Model usage refresh integration.
 - `token-switch-usage.test.ts` — Token Switch balance formatting.
@@ -65,10 +69,19 @@ In addition to automated tests, validate HUD behavior in a real Pi TUI across di
 
 ## Code style
 
-The project currently has no configured linter, formatter, or pre-commit hook. Follow the existing conventions:
+The project uses ESLint for code-quality checks and Prettier for deterministic formatting:
+
+```bash
+npm run lint
+npm run lint:fix
+npm run format:check
+npm run format
+```
+
+Follow the configured conventions:
 
 - Use TypeScript ESM and explicit types.
-- Use two-space indentation, double quotes, and semicolons.
+- Use tab indentation, double quotes, and semicolons.
 - Keep extension lifecycle handling clear and release timers and UI state during `session_shutdown`.
 - Do not edit content enclosed by `AUTO-GENERATED` markers manually; regenerate it from the source identified in the marker.
 
@@ -78,32 +91,43 @@ Do not add ignore rules, skip tests, or weaken types merely to bypass a check.
 
 The HUD extension is organized into functional modules under `extensions/hud/`:
 
-- **`index.ts`** — Lifecycle and side-effect orchestration.
+- **`index.ts`** — Composition root for controllers, shared state, and UI installation.
+- **`commands/`** — `/zentui` presentation and its configuration-persistence controller.
 - **`config/`** — Configuration model, normalization, and persistence.
-- **`footer/`** — Footer rendering, categorized layout, and template parsing.
+- **`footer/`** — Footer rendering, semantic group construction, responsive layout, and templates.
 - **`segments/`** — State collectors: Git, runtime, MCP, skills, projects, etc.
+- **`session/`** — Pi event registration, lifecycle generations, and live-context throttling.
+- **`state/`** — Shared footer state, telemetry reducer, and project-refresh controller.
 - **`telemetry/`** — Usage formatting, token switch, and Codex subscription client.
-- **`session/`** — Session lifecycle, context, and live context overlay.
-- **`state/`** — Aggregated state, telemetry, and project refresh.
-- **`commands/`** — `/zentui` command and interactive TUI settings.
 - **`ui/`** — Icons and terminal style utilities.
 
 Key conventions:
 
-- Keep event listeners and side-effects in `index.ts`; do not read files or spawn processes in `render()`.
+- Keep composition in `index.ts`, Pi event listeners in `session/event-handlers.ts`, and avoid file reads or subprocesses in `render()`.
 - Async results check session generation before applying.
 - Timers should be cleaned up on shutdown and `unref()` where possible.
 - State collectors return explicit `ok` / `error` / `not found` semantics.
 - Use `visibleWidth()` and `truncateToWidth()` for terminal width calculations.
 
+## Releases
+
+npm releases use GitHub Trusted Publishing through `.github/workflows/publish.yml`; no `NPM_TOKEN` repository secret is required. The workflow has narrowly scoped `id-token: write` permission, verifies the package, and publishes with provenance.
+
+1. Update the same version in `package.json` and `package-lock.json`.
+2. Commit and push the release changes to `main`.
+3. Create an annotated tag that exactly matches the package version, for example `git tag -a v1.1.0 -m "v1.1.0"`.
+4. Push the tag with `git push origin v1.1.0`.
+5. Confirm the **Publish npm package** workflow succeeds and verify the version on npm.
+
+The tag/version guard fails the workflow before publication if they do not match.
+
 ## Pull request checklist
 
 Before opening a pull request, confirm that:
 
 - [ ] The change has a focused scope and contains no unrelated files.
 - [ ] New behavior or bug fixes include appropriate tests.
-- [ ] `npm test` passes.
-- [ ] `npm run typecheck` passes.
+- [ ] `npm run verify` passes (format, types, lint, and tests).
 - [ ] `npm run pack:check` passes and the package contains the expected files.
 - [ ] Affected HUD behavior was verified in a real Pi TUI.
 - [ ] Related documentation was synchronized from its source of truth.

package/docs/README.zh-CN.md

@@ -12,17 +12,18 @@
 
 </div>
 
-Rinco Pi HUD 为 Pi TUI 会话提供丰富的实时状态脚注，可显示项目状态、Git 指标、运行时版本、会话活动、模型用量、Token 费用等信息，支持可配置的三行或单行布局。Pi 可直接加载 TypeScript 扩展，无需构建步骤（`tsconfig.json` 设置了 `noEmit: true`，仅用于 `npm run typecheck` 类型检查）。
+Rinco Pi HUD 为 Pi TUI 会话提供丰富的实时状态脚注，可显示项目状态、Git 指标、运行时版本、会话活动、模型用量、Token 费用等信息，支持响应式四分组布局或可定制的单行布局。Pi 可直接加载 TypeScript 扩展，无需构建步骤（`tsconfig.json` 设置了 `noEmit: true`，仅用于 `npm run typecheck` 类型检查）。
 
 ## 功能
 
-- **Project state**：当前目录、Git 分支、Commit、Tag、工作区状态、差异指标和运行时版本。
-- **Session activity**：模型、Provider、Context 用量、Token、缓存、会话费用、轮次和 Thinking 等级。
-- **Tool and agent activity**：Native Tool 完成次数、正在运行的 Tool、活跃 Agent 数、Skill 和 MCP Server 状态。
+- **Project state**：当前目录、Git 分支、Commit、Tag、工作区状态、Git 操作状态、差异指标和运行时版本。
+- **Session activity**：模型、Provider、Context 用量、可独立控制的输入/输出 Token、缓存、会话费用、轮次和 Thinking 等级。
+- **Tool and agent activity**：可分别控制正在运行的 Tool、已完成 Tool 计数、活跃 Agent、空闲状态、Skill 和 MCP Server 状态。
 - **Model quota**：根据当前模型自动切换 Codex 周限额或 Token Switch 余额。
 - **Git awareness**：分支、Detached HEAD、Tag、Ahead/Behind、Stash、合并冲突和脏状态。
 - **Runtime detection**：支持 Node、Python、Go、Rust、Java 等 60+ 运行时，并解析项目清单版本。
-- **Configurable layout**：默认三行分类布局，或完全自定义的单行模板。
+- **Configurable layout**：默认使用响应式 Project、Session、Activity、Usage 四分组布局，或完全自定义的单行模板。
+- **Granular status controls**：可在 `/zentui` 中分别控制 Git 操作状态、Tool 运行状态/计数、Agent 活跃/空闲状态及输入/输出 Token。
 - **Extension statuses**：读取第三方扩展发布的状态，按配置的位置和颜色模式显示。
 - **Safe fallback**：超时和错误处理优雅，会话关闭后不留过期数据。
 
@@ -69,6 +70,10 @@ HUD 脚注默认启用。运行 `/zentui` 打开交互式设置。
 /zentui statusline enable
 /zentui statusline disable
 /zentui statusline toggle
+/zentui row project toggle
+/zentui row session disable
+/zentui row activity enable
+/zentui row usage toggle
 /zentui format clear
 /zentui format "$model · $context · $cost · $git_branch( $git_commit) · $session_duration"
 /codex-status
@@ -82,24 +87,24 @@ HUD 脚注默认启用。运行 `/zentui` 打开交互式设置。
 
 | 路径 | 说明 |
 | --- | --- |
-| [`extensions/hud/index.ts`](../extensions/hud/index.ts) | 扩展生命周期与副作用编排 |
-| [`extensions/hud/config/`](../extensions/hud/config/config.ts) | 配置模型、归一化与持久化 |
-| [`extensions/hud/footer/`](../extensions/hud/footer/index.ts) | 脚注渲染、分类布局与模板解析 |
+| [`extensions/hud/index.ts`](../extensions/hud/index.ts) | Controller、共享状态与 UI 安装的组合入口 |
+| [`extensions/hud/config/`](../extensions/hud/config/config.ts) | 配置模型、归一化、迁移与持久化 |
+| [`extensions/hud/footer/`](../extensions/hud/footer/index.ts) | 脚注渲染、语义分组、响应式布局与模板解析 |
 | [`extensions/hud/segments/`](../extensions/hud/segments/) | 状态采集器：Git、运行时、MCP、Skill、项目等 |
 | [`extensions/hud/telemetry/`](../extensions/hud/telemetry/format.ts) | 用量格式化、Token Switch 与 Codex 订阅客户端 |
-| [`extensions/hud/session/`](../extensions/hud/session/) | 会话生命周期、上下文与实时上下文覆盖 |
-| [`extensions/hud/state/`](../extensions/hud/state/) | 聚合状态、遥测与项目刷新 |
-| [`extensions/hud/commands/`](../extensions/hud/commands/settings.ts) | `/zentui` 命令与交互式 TUI 设置 |
+| [`extensions/hud/session/`](../extensions/hud/session/) | Pi 事件注册、会话生命周期与实时 Context 覆盖 |
+| [`extensions/hud/state/`](../extensions/hud/state/) | 聚合状态、Telemetry Reducer 与项目刷新 Controller |
+| [`extensions/hud/commands/`](../extensions/hud/commands/settings.ts) | `/zentui` 设置界面与配置 Controller |
 | [`extensions/hud/ui/`](../extensions/hud/ui/) | 图标与终端样式工具 |
 | [`docs/footer.md`](footer.md) | 完整脚注配置参考 |
 | [`docs/CONTRIBUTING.md`](CONTRIBUTING.md) | 本地开发、测试规范和 PR 检查清单 |
-| [`tests/`](../tests/) | Vitest 测试套件（34+ 测试用例，6 个文件） |
+| [`tests/`](../tests/) | Vitest 测试套件（41 个测试用例，8 个文件） |
 
 ## 定制
 
 ### 布局
 
-默认三行布局将项目、会话和用量信息分组显示。设置 `footerFormat` 模板字符串可切换为单行布局：
+默认布局将信息分为 Project、Session、Activity 和 Usage 四组；超长分组会在完整状态项边界处换行，并保持续行对齐。设置 `footerFormat` 模板字符串可切换为单行布局：
 
 ```text
 /zentui format "$cwd( $git_branch)$fill($context)( $tokens)( $cost)"
@@ -109,14 +114,25 @@ HUD 脚注默认启用。运行 `/zentui` 打开交互式设置。
 
 ### 状态段
 
-通过 `/zentui` 启用或禁用单个状态段：
+运行 `/zentui` 并进入 **Built-in segments**，即可启用或禁用单个状态：
+
+| 分组 | 可独立控制的状态 |
+| --- | --- |
+| Project | Git 状态、Git 操作状态（`MERGING`、`REBASING` 等）、Commit、差异指标、运行时、包版本、OS 和用户 |
+| Session | 模型、Thinking 等级、轮次和会话时长 |
+| Activity | 正在运行的 Tool、已完成 Tool 计数、活跃 Agent、`Agent idle`、Skill 和 MCP |
+| Usage | Context、输入 Token、输出 Token、缓存详情/命中率、费用、限额和时间 |
+
+使用旧版聚合开关 `tokens`、`toolActivity` 或 `agentActivity` 的配置会自动迁移。仍可通过 `/zentui statusline enable|disable|toggle` 控制整个脚注。
+
+默认四行布局中的每个语义行也可以通过命令单独控制：
 
 ```text
-/zentui statusline enable
-/zentui statusline disable
-/zentui statusline toggle
+/zentui row <project|session|activity|usage> <enable|disable|toggle>
 ```
 
+行开关会持久化到 `footerRows`。使用自定义单行 `footerFormat` 时，这些开关不生效。
+
 ### 扩展状态
 
 第三方扩展发布的状态可由 HUD 脚注显示。可为每个扩展状态键配置位置（`left`、`middle`、`right`、`off`）和颜色模式（`zentui`、`original`）。
@@ -160,11 +176,10 @@ npm test
 npm run typecheck
 ```
 
-验证测试与发布内容：
+验证格式、类型、Lint、测试与发布内容：
 
 ```bash
-npm test
-npm run typecheck
+npm run verify
 npm run pack:check
 ```
 

package/docs/footer.md

@@ -2,46 +2,62 @@
 
 ## Default layout
 
-When `footerFormat` is empty, the HUD displays a three-line categorized layout:
+When `footerFormat` is empty, the HUD displays four semantic groups:
 
 ```text
-⌂ project · pi-sakura ·  main ·  24.18
-λ session · gpt-5.3 · high · ↺ 8 · ★ 2/3 · ⊕ 2/2
-◉ usage · 35%/200k · ↑ 4.2k · ↓ 1.1k · $ 0.030
+Project  · pi-sakura ·  main ·  24.18
+Session  · gpt-5.3 · Thinking level: high · Turn 8
+Activity · Agent idle · Skill 2/3 · MCP 2/2
+Usage    · 35%/200k · ↑ 4.2k · ↓ 1.1k · $ 0.030
 ```
 
-Each line independently computes visible width. Extension statuses are appended to the second line by placement (`left`, `middle`, `right`). When space is tight, lines are truncated at the end with an ellipsis.
+The category column is sized from visible text so every separator aligns. When a row exceeds the terminal width, complete status segments move to an indented continuation line. Only a single segment that is wider than the available content area is truncated. Third-party extension statuses appear on the Activity group in configured `left`, `middle`, then `right` order.
+
+Control each default-layout row independently:
+
+```text
+/zentui row project enable
+/zentui row session disable
+/zentui row activity toggle
+/zentui row usage toggle
+```
+
+The command shape is `/zentui row <project|session|activity|usage> <enable|disable|toggle>`. Values persist under `footerRows`; all four default to `true`. Row switches apply only to the default layout and do not alter a custom single-line `footerFormat`.
 
 ## Built-in status segments
 
-| Key | Default | Line | Description |
+| Key | Default | Group | Description |
 | --- | --- | --- | --- |
-| `os` | on | 1 | OS icon/text per platform |
-| `username` | off | 1 | `user@hostname` |
-| `cwd` | on | 1 | Current working directory |
-| `gitBranch` | on | 1 | Branch name or `HEAD` when detached |
-| `gitStatus` | on | 1 | Conflicts, staged, modified, untracked, stash, ahead/behind |
-| `gitCounts` | off | sub | Numeric counts for ahead/behind and stash |
-| `gitCommit` | off | 1 | Short commit hash and optional exact tag |
-| `gitMetrics` | off | 1 | Added/deleted lines from `git diff HEAD --numstat` |
-| `packageVersion` | off | 1 | Project manifest version |
-| `runtime` | on | 1 | Detected language/build system and tool version |
-| `configCounts` | off | 1 | Instruction files and installed Pi packages count |
-| `sessionName` | on | 2 | Current Pi session name |
-| `model` | on | 2 | Provider and model ID |
-| `thinking` | on | 2 | Thinking level when reasoning-capable |
-| `turnCount` | on | 2 | Current turn index |
-| `skills` | on | 2 | Active/available skills count, e.g. `★ 1/3` |
-| `mcp` | on | 2 | MCP connected/total servers |
-| `toolActivity` | on | 2 | Native tool completion count or recent running status |
-| `agentActivity` | on | 2 | Active primary agent runs |
-| `context` | on | 3 | Context percentage, window size, and/or gauge |
-| `tokens` | on | 3 | Input, output, cache token summary |
-| `cacheDetails` | on | 3 | Cumulative cache read/write tokens |
-| `cost` | on | 3 | Cumulative session cost |
-| `codexUsage` | on | 3 | Codex weekly quota remaining |
-| `sessionDuration` | off | 3 | Current session duration |
-| `time` | off | 3 | Current time `HH:MM` |
+| `cwd` | on | Project | Current working directory |
+| `gitBranch` | on | Project | Branch name or `HEAD` when detached |
+| `gitStatus` | on | Project | Conflicts, staged, modified, untracked, stash, ahead/behind |
+| `gitState` | on | Project | Git operation state such as `MERGING` or `REBASING` |
+| `gitCounts` | off | Project | Numeric counts embedded in ahead/behind and stash status |
+| `gitCommit` | off | Project | Short commit hash and optional exact tag |
+| `gitMetrics` | off | Project | Added/deleted lines from `git diff HEAD --numstat` |
+| `runtime` | on | Project | Detected language/build system and tool version |
+| `packageVersion` | off | Project | Project manifest version |
+| `configCounts` | off | Project | Instruction files and installed Pi packages count |
+| `os` | on | Project | OS icon/text per platform |
+| `username` | off | Project | `user@hostname` |
+| `sessionName` | on | Session | Current Pi session name |
+| `model` | on | Session | Provider and model ID |
+| `thinking` | on | Session | Thinking level when reasoning-capable |
+| `turnCount` | on | Session | Current turn index |
+| `sessionDuration` | off | Session | Current session duration |
+| `runningTools` | on | Activity | Currently running native tools and elapsed time |
+| `toolCounts` | on | Activity | Cumulative completed native-tool counts |
+| `activeAgents` | on | Activity | Active primary agent runs |
+| `agentIdle` | on | Activity | `Agent idle` when no primary agent run is active |
+| `skills` | on | Activity | Active/available skills count, e.g. `Skill 1/3` |
+| `mcp` | on | Activity | MCP connected/total servers |
+| `context` | on | Usage | Context percentage, window size, and/or gauge |
+| `inputTokens` | on | Usage | Cumulative input tokens |
+| `outputTokens` | on | Usage | Cumulative output tokens |
+| `cacheDetails` | on | Usage | Cache read/write tokens and latest hit rate |
+| `cost` | on | Usage | Cumulative session cost |
+| `codexUsage` | on | Usage | Codex weekly quota remaining |
+| `time` | off | Usage | Current time `HH:MM` |
 
 ## Template syntax
 
@@ -100,7 +116,7 @@ Clear it:
 | `$instruction_files` | `AGENTS.md` + `CLAUDE.md` total |
 | `$agents_files` | `AGENTS.md` count |
 | `$claude_files` | `CLAUDE.md` count |
-| `$skills` | Active/available skills, e.g. `★ 1/3` |
+| `$skills` | Active/available skills, e.g. `Skill 1/3` |
 | `$active_skills` | Active skills count only |
 | `$extensions` | Installed Pi packages count |
 | `$mcp` | MCP connected/total |

package/extensions/hud/commands/settings-controller.ts

@@ -0,0 +1,78 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	type PolishedTuiConfig,
+	saveColorSourcesPatch,
+	saveContextStylePatch,
+	saveExtensionStatusColorMode,
+	saveExtensionStatusPlacement,
+	saveFooterFormatPatch,
+	saveFooterRowsPatch,
+	saveFooterSegmentsPatch,
+	saveGitBranchPatch,
+	saveIconsModePatch,
+	savePathDisplayPatch,
+	saveSeparatorPatch,
+	saveUiFeaturesPatch,
+} from "../config/config.js";
+import { registerZentuiSettingsCommand } from "./settings.js";
+
+interface SettingsControllerDeps {
+	getConfig: () => PolishedTuiConfig;
+	setConfig: (config: PolishedTuiConfig) => void;
+	applyConfiguredUi: (ctx: ExtensionContext) => void;
+	restartSessionTimer: () => void;
+	getActiveExtensionStatuses: () => ReadonlyMap<string, string>;
+	requestRender: () => void;
+}
+
+/** Connect the settings UI to persistence without exposing patch mechanics to the extension root. */
+export function registerSettingsController(pi: ExtensionAPI, deps: SettingsControllerDeps): void {
+	const updateConfig = (config: PolishedTuiConfig) => {
+		deps.setConfig(config);
+	};
+
+	registerZentuiSettingsCommand(pi, {
+		getConfig: deps.getConfig,
+		setColorSources(patch) {
+			updateConfig(saveColorSourcesPatch(patch));
+		},
+		setUiFeatures(patch, ctx) {
+			updateConfig(saveUiFeaturesPatch(patch));
+			deps.applyConfiguredUi(ctx);
+		},
+		setFooterRows(patch) {
+			updateConfig(saveFooterRowsPatch(patch));
+		},
+		setFooterSegments(patch) {
+			updateConfig(saveFooterSegmentsPatch(patch));
+			deps.restartSessionTimer();
+		},
+		setFooterFormat(value) {
+			updateConfig(saveFooterFormatPatch(value));
+			deps.restartSessionTimer();
+		},
+		setIconMode(mode) {
+			updateConfig(saveIconsModePatch(mode));
+		},
+		setContextStyle(style) {
+			updateConfig(saveContextStylePatch(style));
+		},
+		setSeparator(separator) {
+			updateConfig(saveSeparatorPatch(separator));
+		},
+		setPathDisplay(patch) {
+			updateConfig(savePathDisplayPatch(patch));
+		},
+		setGitBranch(patch) {
+			updateConfig(saveGitBranchPatch(patch));
+		},
+		getActiveExtensionStatuses: deps.getActiveExtensionStatuses,
+		setExtensionStatusPlacement(key, placement) {
+			updateConfig(saveExtensionStatusPlacement(key, placement));
+		},
+		setExtensionStatusColorMode(key, colorMode) {
+			updateConfig(saveExtensionStatusColorMode(key, colorMode));
+		},
+		requestRender: deps.requestRender,
+	});
+}