@erichll/pi-statusline 0.4.1 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,85 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.0 - 2026-10-16
4
+
5
+ ### Added
6
+
7
+ - Add a tool activity row between the main line and the runtime row, shown
8
+ once the current run has used tools: `◐ bash npm test 12s · ✓ read ×5 ·
9
+ ✗ bash ×1 · +2`. Up to two running tools show their target (shell command
10
+ without `cd`/env prefixes, file name, search pattern or directory) and timer;
11
+ same-name calls merge as `×N`. Completed (`✓`) and failed (`✗`) calls are
12
+ counted per run and kept in the last-run summary.
13
+ - Count nested calls (`parentToolCallId`) but represent them by their parent
14
+ while running. Calls ended by a user cancellation are not counted as failures.
15
+ - Add a `session` segment on the runtime row, enabled by default: the time
16
+ since the session was created (`󰥔 2h 6m`; `◷` in Unicode and `ses:` in ASCII
17
+ icon modes), to the minute and before session tokens. It is read once per
18
+ session from Pi's session header, survives reloads and resuming, restarts with
19
+ `/new` or a fork, and is hidden when the header time is missing or invalid.
20
+ Existing segment lists gain it before `tokens` unless they list it explicitly.
21
+ - Add `runtime.toolsMaxVisible` (1–8, default 4) for completed tool kinds shown
22
+ before `+N`, editable in the panel. Narrow rows fold kinds, then drop targets,
23
+ then timers.
24
+ - Label quota windows from the reported length (`x-codex-*-window-minutes`
25
+ headers and WebSocket `window_minutes`): `5h`, `1d`, `7d` or `30d` within 5%,
26
+ otherwise exact (`1h30m`). Without a reported length a window stays unlabeled
27
+ rather than guessed; a malformed length drops only the label.
28
+ - Add tool target, tool counting, window label, per-window color and session age
29
+ tests, and extend the offline PTY smoke with the tool row, completed counts
30
+ and session age.
31
+
32
+ ### Changed
33
+
34
+ - Render quota as `5h ███░░░░░░░ 27% 4h8m · 7d ████░░░░░░ 44% 6d1h`: dim labels
35
+ and `·` separators, muted countdowns without brackets, and each window colored
36
+ by its own usage (accent, warning above 70%, error above 90%). An explicit
37
+ segment `color` still applies to both. Unlabeled windows keep their countdown
38
+ instead of their bar on narrow terminals.
39
+ - Restyle the runtime row and move it to the bottom of the footer. A run status
40
+ symbol (`●` running, `✓` done, `✗` failed, `⊘` cancelled) precedes the
41
+ duration in place of `Elapsed`; labels are dim and lowercase
42
+ (`avg 39 tok/s · cache 100% · 11 turns · 1 compaction`); cache is green from
43
+ 80% and warning below 50%. ASCII mode uses `*`, `ok`, `x` and `-`.
44
+ - Keep average speed and cache visible while tools run or input is awaited.
45
+ `awaiting input`, `no content` and `compacting…` follow the duration in the
46
+ warning color; `no content` was previously muted.
47
+ - Move the session token total (`tokens`) from the main line to the runtime row,
48
+ before other extensions' statuses. It keeps its icon, color and enablement.
49
+ - `runtime.tools` now controls the tool row. Existing configurations with
50
+ `"tools": true` show it after upgrading; set it to `false` to hide it.
51
+
52
+ ### Removed
53
+
54
+ - Remove `Tool X 3s` / `Tools N active` from the runtime row; the tool row
55
+ replaces them.
56
+
57
+ ## 0.5.0 - 2026-10-14
58
+
59
+ ### Added
60
+
61
+ - Add Codex subscription Usage (`quota`) with primary/secondary progress bars,
62
+ used percentages and live reset countdowns. Passively observe SSE response
63
+ headers and native WebSocket `codex.rate_limits` events on Pi 1.2+, with no
64
+ extra requests or credential lookups. Existing statusline features retain
65
+ Pi 1.1 support.
66
+ - Enable quota after context by default, including in existing configurations
67
+ that omit it. Explicit quota settings preserve enablement and order;
68
+ the panel supports disabling, reordering and styling it.
69
+ - Use accent/warning/error colors at the 70%/90% usage thresholds, with ASCII
70
+ support and narrow-screen fallback to bars, percentages or hiding the segment.
71
+ - Hide missing, malformed and expired quota windows; replace snapshots rather
72
+ than merge credentials' data. Clear old samples on model/provider/API/endpoint
73
+ changes, reload, new session, footer disable and no-quota WebSocket streams.
74
+ - Add quota parser, lifecycle, countdown and rendering tests, plus offline
75
+ regular/fullscreen PTY coverage for both headers and WebSocket events.
76
+
77
+ ### Changed
78
+
79
+ - Simplify context bars from `[██░░░░░░░░]20%` to `██░░░░░░░░ 20%`.
80
+ - Condense the README around installation, configuration, quota setup and
81
+ statistics; link to the complete example configuration instead of duplicating it.
82
+
3
83
  ## 0.4.1 - 2026-10-13
4
84
 
5
85
  - Upgrade the Pi 1.2.0 development baseline (`pi-ai`, `pi-coding-agent`,
package/README.md CHANGED
@@ -1,43 +1,29 @@
1
1
  # @erichll/pi-statusline
2
2
 
3
- A configurable footer for Pi 1.1 with Git status, session usage, runtime/tool activity, themes, and live configuration preview. Uses Pi's native footer and leaves the editor intact.
3
+ A configurable native Pi footer with Git status, session usage, runtime/tool
4
+ activity and live configuration preview. Leaves the editor intact.
4
5
 
5
6
  ```text
6
-  Example model(high)  󰆼 [█░░░░░░░░░]11.9%  󰉋 pi-packages   main ● *2 ↑2  󰊄 49.4k
7
- Elapsed 5m 42s · Avg 45 tok/s · Cache 86% · Turns 3 · Compactions 1
7
+  Example model(high)  󰆼 █░░░░░░░░░ 11.9%  󰉋 pi-packages   main ● *2 ↑2
8
+ ◐ bash npm test 12s · ✓ read ×5 · ✓ edit ×2
9
+ ● 5m 42s · avg 45 tok/s · cache 86% · 3 turns · 1 compaction · 󰥔 2h 6m · 󰊄 49.4k
8
10
  ```
9
11
 
12
+ Rows, top to bottom: the main segments, tool activity for the current run
13
+ (only once it has used tools), then run status, run metrics, session age and
14
+ tokens, and other extensions' statuses.
15
+
10
16
  ## Install
11
17
 
12
18
  ```sh
13
19
  pi install npm:@erichll/pi-statusline
14
20
  ```
15
21
 
16
- Requires Node.js >=22.19, Pi >=1.1.0, a Nerd Font for the default Powerline layout,
17
- and optionally Git. Switch icons/separators in the panel for a font-independent
18
- layout. The package has no
19
- other runtime dependencies and makes no network requests or credential lookups.
20
- Only one extension should own Pi's footer, so disable any other footer
21
- extension in `pi config` before enabling this one.
22
-
23
- ## Local use
24
-
25
- From this repository, try the extension for one invocation:
26
-
27
- ```sh
28
- npm install
29
- pi --no-extensions --extension ./packages/pi-statusline/src/index.ts
30
- ```
31
-
32
- `--no-extensions` disables other auto-discovered extensions for this invocation.
33
- To use your other extensions, disable `pi-powerline-footer` in `pi config`
34
- before starting Pi with `--extension ./packages/pi-statusline/src/index.ts`.
35
- Only one extension should own the footer. The previous package can remain
36
- installed for rollback. Loading this repository as a whole also discovers the
37
- security extensions; use the statusline entrypoint to try it on its own.
38
-
39
- This checkout is for development only. For a persistent install use the
40
- published package, `npm:@erichll/pi-statusline`.
22
+ Requires Node.js >=22.19 and Pi >=1.1.0; subscription Usage requires Pi >=1.2.0.
23
+ Git is optional. The default Powerline layout requires a Nerd Font; choose
24
+ ASCII icons and plain separators for a font-independent layout.
25
+ Disable other footer extensions in `pi config`: only one should own the footer.
26
+ No extra network requests or credential lookups are made.
41
27
 
42
28
  ## Commands
43
29
 
@@ -46,292 +32,162 @@ published package, `npm:@erichll/pi-statusline`.
46
32
  | `/statusline` | Open configuration and live preview |
47
33
  | `/statusline on` | Enable for this session |
48
34
  | `/statusline off` | Restore Pi's native footer for this session |
49
- | `/statusline reload` | Reload saved configuration, including startup enablement |
50
-
51
- The panel supports arrow navigation, Space to toggle a segment, Alt+Up/Down to
52
- reorder it, and Enter to edit its properties. Choose **Save and apply globally**
53
- to persist the draft. Esc backs out of a property editor or cancels the panel.
54
- **Runtime options** edits the same draft; Space toggles booleans and Enter edits
55
- the no-content threshold.
56
- **Restore defaults in preview** changes only the draft until saved.
57
- Preview uses the real footer renderer and current session data, or clearly
58
- labelled example data for an empty session. A save error leaves the active
59
- configuration unchanged and keeps the panel open.
35
+ | `/statusline reload` | Reload saved configuration |
36
+
37
+ In the panel: arrows navigate, Space toggles, Alt+Up/Down reorders segments,
38
+ Enter edits, and Esc backs out or cancels. **Save and apply globally** persists
39
+ changes; **Restore defaults in preview** only changes the draft until saved.
40
+ Thinking settings are under **model**; runtime settings are under **Runtime options**.
60
41
 
61
42
  ## Configuration
62
43
 
63
- Settings live in `extensions/pi-statusline/config.json` under Pi's agent directory,
64
- normally `~/.pi/agent/extensions/pi-statusline/config.json`;
65
- `PI_CODING_AGENT_DIR` is respected. The extension
66
- does not write Pi's general `settings.json`. Configuration is global, with no
67
- project override or file watcher. After manual changes use `/statusline reload`.
68
- The configuration directory is created automatically when saving from the panel.
69
- When upgrading from the previous `~/.pi/agent/statusline.json` location, move the
70
- existing file to the new path before running `/reload`; the old path is no longer read.
44
+ Settings are global, stored at
45
+ `~/.pi/agent/extensions/pi-statusline/config.json` (`PI_CODING_AGENT_DIR` is
46
+ respected). After manual edits, run `/statusline reload`; after source edits,
47
+ run Pi's `/reload` instead. The old `~/.pi/agent/statusline.json` path is no
48
+ longer read—move an existing file to the new location when upgrading.
49
+
50
+ Use the panel or start with a partial configuration:
71
51
 
72
52
  ```json
73
53
  {
74
- "version": 1,
75
- "enabled": true,
76
- "preset": "powerline",
77
- "icons": "nerd",
78
- "separator": "powerline",
79
- "pathMode": "basename",
80
- "modelDisplay": "name",
81
- "contextDisplay": "bar",
82
- "spacing": 1,
83
- "segments": [
84
- {
85
- "id": "model",
86
- "enabled": true
87
- },
88
- {
89
- "id": "thinking",
90
- "enabled": true
91
- },
92
- {
93
- "id": "context",
94
- "enabled": true
95
- },
96
- {
97
- "id": "directory",
98
- "enabled": true
99
- },
100
- {
101
- "id": "git",
102
- "enabled": true
103
- },
104
- {
105
- "id": "cost",
106
- "enabled": false
107
- },
108
- {
109
- "id": "input",
110
- "enabled": false
111
- },
112
- {
113
- "id": "output",
114
- "enabled": false
115
- },
116
- {
117
- "id": "tokens",
118
- "enabled": true
119
- },
120
- {
121
- "id": "cacheRead",
122
- "enabled": false
123
- },
124
- {
125
- "id": "cacheWrite",
126
- "enabled": false
127
- },
128
- {
129
- "id": "statuses",
130
- "enabled": true
131
- }
132
- ],
133
- "runtime": {
134
- "enabled": true,
135
- "status": true,
136
- "tools": true,
137
- "noContent": true,
138
- "noContentSeconds": 10,
139
- "avg": true,
140
- "cache": true,
141
- "counts": true,
142
- "retainSummary": true
143
- }
54
+ "icons": "ascii",
55
+ "separator": "pipe",
56
+ "modelDisplay": "last",
57
+ "contextDisplay": "text",
58
+ "spacing": 0
144
59
  }
145
60
  ```
146
61
 
147
- - Layout: `powerline` is the only preset; there is no preset selector.
148
- Customize segments and styles directly, or restore defaults in preview.
149
- Pi's current light/dark theme supplies semantic colors; Powerline backgrounds
150
- adapt to its appearance.
151
- - Icons: `nerd` (default; requires a Nerd Font), `unicode`, `ascii`. ASCII mode
152
- replaces built-in decorative glyphs, not user-provided names or custom icons.
153
- Both graphical modes use `` for the model by default; this glyph requires a
154
- Nerd Font. A custom model icon still overrides the default.
155
- - Separators: `powerline` (default), `pipe`, `dot`, `space`. ASCII mode uses plain separators.
156
- - Paths: `basename`, `abbreviated`, `full` (home directory abbreviated as `~`).
157
- - Model display: `name` (default) uses the display name with full ID fallback.
158
- Choose `last` for the final non-empty `/`-separated component of the **model ID**,
159
- even when a display name is configured. For example, `provider/a/b/c/d` becomes `d`.
160
- Restoring defaults resets this preference to `name`.
161
- - Context display: `bar` (default, `[██░░░░░░░░]20%`) or `text`
162
- (`12.7k/272k(4.7%)`). Choose **Context display: bar** in the panel or set
163
- `"contextDisplay": "bar"`.
164
- The ten-cell bar uses whole blocks to avoid gaps inside partial glyphs. Fill
165
- rounds to the nearest cell, with at least one filled cell for non-zero usage;
166
- the percentage retains the more precise value. ASCII mode uses `#` and `-`.
167
- Unknown usage shows `[??????????]?%`; values above 100% fill
168
- the bar completely and retain the reported percentage. Both modes use the
169
- existing context warning colors. Text mode includes token counts and capacity;
170
- bar mode shows progress and percentage.
171
- - Spacing: `1` (default), `0`, `2` or `3` blank lines above the statusline.
172
- Pi renders the footer directly under the editor, so this is the only supported
173
- way to add breathing room between the input box and the statusline; the editor's
174
- own bottom border cannot be removed. Choose **Spacing above statusline** in the
175
- panel or set `"spacing": 0` for a flush footer.
176
- - `segments`: optional ordered array of `{ id, enabled, icon?, color?, iconColor?, background? }`.
177
- An explicit list is authoritative: omitted segments are disabled but remain
178
- available in the panel. The `statuses` segment always occupies the second row.
179
- Preset layouts place context immediately after the model, before directory
180
- and Git. Explicit saved segment order is respected and can be changed in the panel.
181
- - Thinking is appended to the model as `(level)`, with no separate icon or
182
- separator. In the panel, edit **model → Thinking level / Thinking color**.
183
- The existing `thinking` configuration entry controls suffix enablement and an
184
- optional color override; its position, icon and background are ignored. It
185
- does not render on its own when the model is hidden or non-reasoning.
186
- By default, `off`, `minimal`, `low`, and `medium` use their respective Pi theme
187
- colors; `high`, `xhigh`, and `max` use a fixed violet/pink/orange/yellow/green/cyan/blue
188
- palette independent of the Pi theme, distributed across the available characters.
189
- The color or rainbow covers the entire `(level)`, including parentheses, and
190
- the model's background covers the whole item.
191
- - Icon `""` hides a glyph. In the panel, enter `:default` to restore its default.
192
- Color fields accept `#RRGGBB` or `text`, `accent`, `muted`, `dim`, `success`,
193
- `warning`, `error`, `border`, `borderAccent`, `borderMuted`, and Pi's
194
- `thinkingOff/Minimal/Low/Medium/High/Xhigh/Max` tokens. Empty color input in the
195
- panel restores the default. Explicit colors override automatic warning colors.
62
+ See [examples/statusline.json](examples/statusline.json) for the complete defaults.
63
+
64
+ | Setting | Values (default first) |
65
+ | --- | --- |
66
+ | `enabled` | `true`, `false` (startup enablement) |
67
+ | `preset` | `powerline` only; colors adapt to Pi's light/dark theme |
68
+ | `icons` | `nerd`, `unicode`, `ascii` |
69
+ | `separator` | `powerline`, `pipe`, `dot`, `space` |
70
+ | `pathMode` | `basename`, `abbreviated`, `full` |
71
+ | `modelDisplay` | `name` (display name/ID), `last` (final model ID component) |
72
+ | `contextDisplay` | `bar` (`██░░░░░░░░ 20%`), `text` (`12.7k/272k(4.7%)`) |
73
+ | `spacing` | `1`, `0`, `2`, `3` blank lines above the footer |
196
74
 
197
75
  Available segments:
198
76
 
199
77
  | ID | Data | Default |
200
78
  | --- | --- | --- |
201
- | `model` | Display name/full ID, or final ID component via `modelDisplay` | On |
202
- | `thinking` | Controls the colored `(level)` suffix inside the model item | On |
203
- | `context` | Text usage/capacity or a progress bar, followed by percentage | On |
204
- | `directory` | Current working directory | On |
205
- | `git` | Branch, clean/dirty/conflict, staged `+`, unstaged `*`, untracked `?`, ahead/behind | On |
206
- | `cost` | Pi-recorded cumulative USD cost; enable in the panel when wanted | Off |
207
- | `tokens` | Cumulative total tokens | On |
208
- | `input`, `output` | Cumulative input or output tokens | Off |
209
- | `cacheRead`, `cacheWrite` | Cumulative cache token counts | Off |
210
- | `statuses` | Other extensions' `setStatus()` text on the runtime row, with terminal controls stripped | On |
211
-
212
- The default Powerline preset enables model/thinking, context, directory, Git, total
213
- tokens and extension statuses. Cost, input/output and cache token counters stay off.
214
- See [examples/statusline.json](examples/statusline.json) for an explicit layout.
215
- Unknown presets or versions, duplicate segments, invalid colors and malformed JSON are
216
- rejected with a notification; reload retains the last working configuration.
217
- Removing the file restores defaults on reload. Saves use an atomic file replacement.
218
- Obsolete `runtime.untilCompact`, `providerMetrics` and `integrations` keys are
219
- ignored and dropped on the next save; they do not require a configuration migration.
220
-
221
- ## Runtime row and compaction
222
-
223
- Runtime metrics use Pi's public events and reported usage, without modifying the
224
- provider. `Elapsed`
225
- leads the second row; no additional `Running 342s` or `Done 342s` duration is
226
- shown. A run starts at the first `agent_start` and ends at `agent_settled`, not
227
- `agent_end`. Retries, tools, UI waits and compaction do not reset its monotonic
228
- clock. `retainSummary` keeps the last run's footer summary until the next run
229
- (disable it to hide the run summary at settlement). The idle
230
- footer has no Idle label or leading separator.
231
-
232
- - `Turns` counts Pi `turn_start` events, not upstream requests. Internal retries
233
- may make more than one request in a turn; no request count is inferred from
234
- turn events. Compaction does not increase the model-turn count.
235
- - Tool activity is keyed by tool-call ID, including concurrent/nested calls and
236
- updates. It shows `Tool bash 26s` or `Tools 2 active`; tools cannot decide the
237
- model run's outcome. Pi UI prompts take precedence with `Awaiting input`.
238
- - `No content 10s` means **no non-empty text, reasoning or tool-call delta has
239
- been observed** for ten seconds. It uses the same muted color as Avg.
240
- It is not a server timeout or request phase.
241
- Tools, compaction and UI waits suppress it. The integer threshold accepts
242
- 1–3600 seconds. Empty deltas and usage-only updates do not reset it.
243
- - Per-run usage includes only actual assistant messages. Streaming counters are
244
- replaced, not repeatedly added. `Avg = output tokens / total run seconds`,
245
- including tools, UI waits, retries and compaction; it is not inference speed.
246
- `Cache = cacheRead / (input + cacheRead + cacheWrite)`. Missing usage/invalid
247
- denominators are unavailable, not made-up zeroes. A genuinely reported zero
248
- remains zero. These values never replace cumulative session totals.
249
- - `Compacting… 4s` suppresses rate/cache noise while
250
- compaction is active. Success restores the base row; failure/cancellation can
251
- show `Compaction failed` / `Compaction cancelled` while no model run is active,
252
- until subsequent activity.
253
- - `Compactions` counts unique successful entries across the **whole session file**,
254
- including other branches, not merely the selected tree path. It is hidden
255
- while the count is zero, including during the first active compaction.
256
- `runtime.enabled: false` hides the statusline's runtime metrics. Individual
257
- options hide their corresponding items; `status` controls the local Elapsed
258
- and compaction-result labels. The `statuses` segment independently controls other
259
- extensions' text. If its `tps` entry is precisely a plain `Elapsed …` duration,
260
- that display text is moved to the front and replaces the local Elapsed item.
261
- All other statuses remain opaque text: they are never parsed into counters or
262
- provider metrics. The provider's Elapsed may use its own pause
263
- semantics; Avg always uses the independent monotonic run clock.
264
-
265
- Runtime summaries are in-memory since extension load; reload/new session resets
266
- them, unlike persisted usage/compaction totals.
267
-
268
- ## Existing provider statuses
269
-
270
- The CLIProxyAPI provider already publishes an Elapsed footer status through
271
- `setStatus("tps", ...)` and a TPS/token-summary notification at settlement. The
272
- statusline can reuse the explicit Elapsed text; it does not parse the notification.
273
- Its own Avg and Cache come from Pi-reported assistant usage and the local run clock.
274
-
275
- No provider changes, adapter handshake or private network instrumentation are
276
- required. Request counts, first-text/reasoning request latency, per-request duration,
277
- transport reporting and retry associations are not exposed by this package. The
278
- provider may implement transports/retries internally without exposing these metrics.
279
-
280
- ## Statistics and refresh behavior
281
-
282
- Context comes from Pi's `getContextUsage()`. It is distinct from cumulative
283
- token consumption. Unknown values, including immediately after compaction, show
284
- `?` until Pi can provide an estimate. Yellow begins above 70%, red above 90%.
285
- Pi 1.0 bases context estimates on persisted messages; in-flight usage updates
286
- the cumulative token/cost segments while context refreshes after persistence.
287
-
288
- Session totals include all usage already recorded in the current session file:
289
- assistant messages, explicit usage entries, tool-result usage, compaction and
290
- branch summaries, including pre-compaction and abandoned-branch consumption.
291
- Streaming responses are provisional and counted once when persisted. The total
292
- token segment sums input, output, cache-read and cache-write, matching Pi's
293
- native session totals. Costs are **Pi-reported values, not provider invoices**;
294
- zero means no cost recorded by Pi. No subscription-quota API or child-session
295
- log is queried, and private `pi-subagents` result details are not parsed.
296
-
297
- Git queries run asynchronously every two seconds and after tool/branch changes,
298
- with a one-second timeout and optional index locks disabled. No repository hides
299
- the segment; failures show `?`, never a false clean state. Large output above
300
- 8 MiB also falls back to unknown. Worktrees, detached HEAD, unborn branches and
301
- filenames containing newlines are supported. Disabling the Git segment stops
302
- its polling.
303
-
304
- Rendering performs no file reads, Git queries or full-session scans. Streaming
305
- refresh requests are coalesced to 100 ms. Narrow terminals shorten model/path
306
- labels, then hide cost, cache/token counters, the thinking suffix, Git and directory in
307
- that order, retaining model/context where possible. The secondary status row
308
- drops extension text and cache/rate first, preserving
309
- leading Elapsed and compaction status where possible, then truncates by terminal
310
- cell width. Reload, session replacement, disabling and shutdown
311
- release timers and subscriptions. RPC, JSON and print mode do not install UI
312
- components or start polling.
313
-
314
- ## Development and rollback
79
+ | `model`, `thinking` | Model and colored `(level)` suffix | On |
80
+ | `context` | Current context usage | On |
81
+ | `quota` | Subscription Usage and reset countdowns; hidden without data | On |
82
+ | `directory` | Current directory | On |
83
+ | `git` | Branch, dirty/conflict state, staged/unstaged/untracked counts, ahead/behind | On |
84
+ | `session` | Time since the session was created, on the bottom row | On |
85
+ | `tokens` | Cumulative session tokens, on the bottom row | On |
86
+ | `cost` | Pi-recorded cumulative USD cost | Off |
87
+ | `input`, `output`, `cacheRead`, `cacheWrite` | Individual session token counters | Off |
88
+ | `statuses` | Other extensions' text, at the end of the bottom row | On |
89
+
90
+ `segments` is an ordered array of
91
+ `{ id, enabled, icon?, color?, iconColor?, background? }`. Omitted segments are
92
+ disabled, **except `quota` and `session`**: old configurations automatically
93
+ gain `quota` after `context` and `session` before `tokens` (or at the end when
94
+ the anchor is absent). To keep one off, include it with `"enabled": false`.
95
+
96
+ Colors accept `#RRGGBB` or supported Pi theme tokens such as `accent`, `muted`,
97
+ `success`, `warning` and `error`; explicit colors override automatic thresholds.
98
+ An empty icon hides it; enter `:default` in the panel to restore its default.
99
+ The `thinking` entry controls the model suffix, not a standalone segment.
100
+
101
+ Invalid configurations retain the last working settings and show a warning.
102
+ Removing the file restores defaults on reload; panel saves are atomic.
103
+
104
+ ## Subscription Usage (Pi 1.2+)
105
+
106
+ Codex quota appears after context when valid data is available:
107
+
108
+ ```text
109
+ 󰆼 █░░░░░░░░░ 4.6%  󰦖 5h ████░░░░░░ 40% 3h3m · 7d ██░░░░░░░░ 21% 4d9h
110
+ ```
111
+
112
+ Bars show **used** percentages for the primary and secondary windows, with live
113
+ reset countdowns. Labels come from the reported window length (`5h`, `1d`,
114
+ `7d`, `30d` within 5%, otherwise exact such as `1h30m`); without one, the
115
+ window is unlabeled rather than guessed. Each window is colored on its own:
116
+ Pi's accent, warning above 70% and error above 90%; a segment `color` overrides
117
+ both. Narrow terminals omit countdowns, then bars, then the segment rather than
118
+ truncate a window; an unlabeled window keeps its countdown instead of its bar.
119
+
120
+ Data is observed passively through Pi's provider events:
121
+
122
+ - **SSE:** `x-codex-{primary,secondary}-{used-percent,reset-at,window-minutes}` response headers.
123
+ CLIProxyAPI needs `requests.passthrough-headers: true`.
124
+ - **WebSocket:** native `codex.rate_limits` events with numeric `used_percent`,
125
+ `reset_at` and optional `window_minutes` in `rate_limits.primary` / `secondary`. Other named metered
126
+ buckets are ignored. The proxy must forward these events.
127
+
128
+ For CLIProxyAPI v8.0.28, each eligible Codex credential needs `websockets: true`
129
+ for the **proxy-to-upstream** WebSocket leg. A downstream WebSocket alone is
130
+ not enough: upstream SSE headers do not become quota frames. This setting is
131
+ separate from `ws-auth` and Pi's transport setting.
132
+
133
+ Missing, malformed or expired windows are hidden; a reported 0% remains visible.
134
+ Each response/event replaces the snapshot without merging credentials' windows.
135
+ Model/provider/API/endpoint changes, reload, new session and footer disable clear
136
+ old data. This is the responding upstream's quota, **not a proxy-pool aggregate**
137
+ or RPM/TPM rate limit.
138
+
139
+ ## Statistics
140
+
141
+ - Context is Pi's current estimate, not cumulative consumption; unknown values
142
+ show `?`. Session totals include recorded usage across the whole session file,
143
+ including compaction and abandoned branches. Cost is Pi-reported, not an invoice.
144
+ - The bottom row starts with the run status (`●` running, `✓` done, `✗` failed,
145
+ `⊘` cancelled) and its duration, which spans retries, tools, UI waits and
146
+ compaction. `avg` is assistant output tokens / total run seconds, **not
147
+ inference speed**; `cache` is cache-read / (input + cache-read + cache-write),
148
+ green from 80% and warning below 50%. `turns` counts Pi turns, not upstream
149
+ requests; `compactions` counts successful session entries.
150
+ - The run duration (to the second) covers one run, from your message until the
151
+ agent settles, across all its turns. The session age (`󰥔 2h 6m`, to the
152
+ minute) counts from the session header's creation time: it survives reloads
153
+ and resuming, restarts with `/new` or a fork, and is hidden when the header
154
+ time is missing or invalid.
155
+ - `awaiting input` and `no content 10s` follow the duration while active. No
156
+ content means no non-empty text, reasoning or tool-call delta was observed; it
157
+ is not a server timeout and is suppressed during tools, UI waits and compaction.
158
+ - The tool row shows up to two running tools with what they work on (a shell
159
+ command without `cd`/env prefixes, a file name or a search pattern), merging
160
+ same-name calls as `×N`, then this run's completed (`✓`) and failed (`✗`)
161
+ counts. `toolsMaxVisible` (1–8, default 4) completed kinds show before `+N`.
162
+ Nested calls count but are represented by their parent while running; calls
163
+ ended by a cancellation are not failures. Narrow rows fold kinds, then drop
164
+ targets, then timers.
165
+
166
+ All runtime options default to enabled; `noContentSeconds` accepts 1–3600
167
+ (default 10). `tools: false` hides the tool row. `retainSummary` keeps the last run until the next one;
168
+ `runtime.enabled: false` hides local runtime metrics. Reload/new session resets
169
+ in-memory runtime summaries, not persisted session totals.
170
+
171
+ Extension statuses remain display-only; a plain `tps` status of `Elapsed …`
172
+ supplies the duration. Git updates asynchronously; no repository
173
+ hides the segment, and query failures show `?`. Narrow layouts prioritize model
174
+ and context. RPC, JSON and print mode do not install the footer or start polling.
175
+
176
+ ## Development
177
+
178
+ From this repository, load only the statusline for one invocation:
315
179
 
316
180
  ```sh
181
+ npm install
182
+ pi --no-extensions --extension ./packages/pi-statusline/src/index.ts
183
+
317
184
  npm run check --workspace @erichll/pi-statusline
318
185
  npm test --workspace @erichll/pi-statusline
319
- # Optional: POSIX PTY integration, using an offline simulated model
320
186
  npm run smoke --workspace @erichll/pi-statusline
321
187
  ```
322
188
 
323
- Tests cover rendering and panel interactions, configuration persistence, runtime
324
- and extension-event wiring, compaction, session usage and real temporary Git
325
- repositories. The POSIX PTY smoke runs **regular and fullscreen**, with isolated
326
- agent/project directories and an entirely offline provider. It covers streaming, nested tools/UI waits,
327
- no-content/cancellation, failed/successful compaction, model/theme changes,
328
- 40-column layout, draft cancel/save, off/on, reload and new session. It writes
329
- `/tmp/pi-statusline-pty-<layout>.log` for diagnosis. To roll back a persistent
330
- installation, disable this extension in `pi config`, re-enable the previous
331
- footer and reload Pi. `/statusline off` restores the native footer, not another
332
- extension's editor or widgets.
333
-
334
- The initial implementation is independently written, with design references to
335
- [pi-powerline-footer](https://github.com/nicobailon/pi-powerline-footer).
336
-
337
- MIT licensed.
189
+ The POSIX PTY smoke uses an offline provider in regular and fullscreen layouts.
190
+ For a persistent install, use the published npm package.
191
+
192
+ Independently implemented with design references to
193
+ [pi-powerline-footer](https://github.com/nicobailon/pi-powerline-footer). MIT licensed.
@@ -21,6 +21,10 @@
21
21
  "id": "context",
22
22
  "enabled": true
23
23
  },
24
+ {
25
+ "id": "quota",
26
+ "enabled": true
27
+ },
24
28
  {
25
29
  "id": "directory",
26
30
  "enabled": true
@@ -41,6 +45,10 @@
41
45
  "id": "output",
42
46
  "enabled": false
43
47
  },
48
+ {
49
+ "id": "session",
50
+ "enabled": true
51
+ },
44
52
  {
45
53
  "id": "tokens",
46
54
  "enabled": true
@@ -67,6 +75,7 @@
67
75
  "avg": true,
68
76
  "cache": true,
69
77
  "counts": true,
70
- "retainSummary": true
78
+ "retainSummary": true,
79
+ "toolsMaxVisible": 4
71
80
  }
72
81
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@erichll/pi-statusline",
3
- "version": "0.4.1",
3
+ "version": "0.6.0",
4
4
  "description": "Configurable Pi statusline with live preview, Git and session usage",
5
5
  "type": "module",
6
6
  "license": "MIT",