@giladbarnea/pi-custom-footer 0.1.13 → 0.1.15

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.
Files changed (3) hide show
  1. package/README.md +6 -6
  2. package/index.ts +61 -36
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  ---
2
- last_updated: 2026-11-12T09-30
2
+ last_updated: 2026-11-14T15-59
3
3
  ---
4
4
 
5
5
  <div align="center">
@@ -30,20 +30,20 @@ Below the editor, see:
30
30
 
31
31
  - **Context remaining at a glance:** a color-graded gauge and used/window tokens.
32
32
  - **Cost across the conversation:** cumulative cost and average cost per assistant turn.
33
- - **Cache behavior:** session hit rate, latest hit or miss, and reused/new token totals. Like Pi’s own notice, a miss shows what it cost and why it happened: an idle gap or a model switch.
33
+ - **Cache behavior:** session hit rate, the last message as `hit 100%` or `miss 45%`, and reused/new token totals. A hit means more than 90% of the prompt was read from the cache. Like Pi’s own notice, a miss that re-billed cached tokens shows what it cost and why it happened: an idle gap or a model switch.
34
34
  - **How long the cache stays warm:** `warm for 26m`, live: the footer redraws once a minute. It counts down to the latest of three times: the last request or cache warm plus the model’s cache lifetime; the end of Pi’s own idle warming, when Pi will refresh this context; and a deadline set with pi-keep-cache-warm in this Pi session. Once that time has passed, the fact hides. Pi’s idle warming counts on Pi 1.5.1 and later; earlier versions show last touch plus lifetime. Models without a declared cache lifetime, such as OpenAI and Codex, show nothing.
35
35
  - **Where you are:** Git branch, dirty marker, directory, and other extensions’ status messages.
36
- - **Subscription pace:** this week’s burn rate against the target rate, as `burn ━━━━●┊─── 1.07× ≤ target 1.18× · resets in 12h`. The sign turns to `>` when you are over budget, and the dot passes the time marker. A reading more than 30 minutes old adds its age, such as `· 2h old`. The age outlasts the pace bar and goes before the rest of the pace. Optional: shown only when a `quota` cache file exists.
36
+ - **Subscription pace:** this week’s pace against the target rate, as `pace ━━━━●┊─── 1.07× ≤ target 1.18× · resets in 12h`. With less room, it reads `pace ≤ target (1.18×)`, then `pace ≤ 1.18×`. The sign turns to `>` when you are over budget, and the dot passes the time marker. A reading more than 30 minutes old adds its age, such as `· 2h old`. The age outlasts the pace bar and goes before the rest of the pace. Optional: shown only when a `quota` cache file exists.
37
37
 
38
- The layout follows your Pi theme. The header and the footer each take the fewest lines they can. To fit, they first drop the pace bar and labels, round readings, remove whitespace, and drop the branch icon. The cache time drops its label (`26m`). Only then does the footer hide facts: a stale reading's age, the burn rate with its reset time, the reused/new split, the session hit rate, the token counts, the word `target`, the cache time, and last the cost per turn. The target rate stays down to `≤ 1.18×`. A cache miss drops its re-billed tokens early. It keeps its cause until every one of those facts has hidden, and keeps its cost to the end. Last, the target rate hides only where it alone would add a line.
38
+ The layout follows your Pi theme. The header and the footer each take the fewest lines they can. To fit, they first drop the pace bar and labels, round readings, remove whitespace, and drop the branch icon. The cache time drops its label (`26m`). A hit or miss drops its percentage. Only then does the footer hide facts: the `sub` mark of a subscription, a stale reading's age, the pace reading with its reset time, the reused/new split, the last message's plain `hit` or `miss`, the token counts, the session hit rate, the word `target`, the cache time, and last the cost per turn. The target rate stays down to `pace ≤ 1.18×`. A cache miss drops its re-billed tokens early. It keeps its cause until every one of those facts has hidden, and keeps its cost to the end. Last, the target rate hides only where it alone would add a line.
39
39
 
40
40
  Skills get one row for every eight terminal rows past the first six, with a minimum of one. A 21-row phone screen gets one row, a 27-row screen two, and a 34-row screen three. To fit, the row first drops token ages, then separators, then shortens long names in the middle (`caut…ctor`). Only then does it hide skills from the end, behind a `+N` count at the end of the last row.
41
41
 
42
42
  **Resize without rescanning the conversation.** The header and footer share cached values. Session changes refresh them, including forks and compaction.
43
43
 
44
- Skill age measures context-token growth since the first response after a skill load. Cache misses mirror Pi’s own miss accounting: the tokens re-billed since the last request or cache warm, their extra cost over cache reads, and the idle time. Costs use the model’s reported pricing, including when you use a subscription.
44
+ Skill age measures context-token growth since the first response after a skill load. Cache misses mirror Pi’s own miss accounting: the tokens re-billed since the last request or cache warm, their extra cost over cache reads, and the idle time. Costs use the model’s reported pricing, including when you use a subscription. Numbers show two decimal places below 10, one from 10, and none from 100.
45
45
 
46
- The pace comes from `~/.cache/quota/provider-usage.json` (or under `XDG_CACHE_HOME`), which the author’s `quota` tool writes. That tool is not public yet, and without the file the footer shows no pace. The reading is for the pool of the session’s model: Claude, Fable or Codex. The footer only reads that file. It never runs `quota` and never fetches. Burn and target each take a color from `quota`’s heat map: green near 1.0×, cool where allowance goes unused, amber then red where it runs out early. A Fable session shows Fable’s target capped by the room left in the shared Claude week.
46
+ The pace comes from `~/.cache/quota/provider-usage.json` (or under `XDG_CACHE_HOME`), which the author’s `quota` tool writes. That tool is not public yet, and without the file the footer shows no pace. The reading is for the pool of the session’s model: Claude, Fable or Codex. The footer only reads that file. It never runs `quota` and never fetches. Pace and target each take a color from `quota`’s heat map: green near 1.0×, cool where allowance goes unused, amber then red where it runs out early. A Fable session shows Fable’s target capped by the room left in the shared Claude week.
47
47
 
48
48
  ## Development
49
49
 
package/index.ts CHANGED
@@ -27,8 +27,9 @@
27
27
  *
28
28
  * Known differences from Pi's cache-miss notice, reviewed November 11, 2026,
29
29
  * against Pi 1.4.0 and 1.5.2:
30
- * - The footer shows any miss above 1,024 tokens. Pi's notice hides a miss
31
- * under 20k tokens that also costs under $0.10.
30
+ * - The footer shows a miss above 1,024 tokens when at most 90% of the
31
+ * prompt was read from the cache. Pi's notice hides a miss under 20k tokens
32
+ * that also costs under $0.10.
32
33
  * - Errored and aborted turns are skipped, as elsewhere in the footer. Pi's
33
34
  * scan includes them.
34
35
  * - The footer scans the current branch. Pi scans every session entry.
@@ -64,6 +65,8 @@ const BRANCH_GLYPH = "";
64
65
  const CONTEXT_GAUGE_SYMBOLS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"];
65
66
  const CONTEXT_GAUGE_STEP_COUNT = CONTEXT_GAUGE_SYMBOLS.length;
66
67
  const CACHE_MISS_NOISE_FLOOR_TOKENS = 1_024;
68
+ // The last message counts as a cache hit when more than this share of its prompt was read from the cache.
69
+ const CACHE_HIT_ABOVE_PERCENT = 90;
67
70
  // Pi's prompt-cache TTL: a miss after a longer idle gap names the gap as its cause.
68
71
  const CACHE_TTL_MS = 5 * 60 * 1000;
69
72
  // Match Theme.fg, which resets the foreground only. A full reset would punch a
@@ -183,28 +186,38 @@ const FOOTER_LADDER: Ladder<FooterFact> = {
183
186
  // "resets in": the bar draws what the two rates say. Then the labels.
184
187
  ["pace", "short"],
185
188
  ["tokens", "short"], ["context", "bare"], ["cacheSession", "bare"], ["expiry", "short"],
186
- // 2. Shorten the readings: the latest cache figure, then the cost, rounded twice.
189
+ // 2. Shorten the readings: the last message's cache share (for a
190
+ // detected miss, its re-billed tokens), then the cost, rounded twice.
187
191
  ["latest", "short"], ["cost", "short"], ["cost", "bare"],
188
192
  // 3. Remove whitespace: the padding inside the cwd pill, then the separators.
189
193
  ["cwd", "short"], ["spacing", "bare"],
190
194
  // 4. Drop the branch icon.
191
195
  ["branch", "bare"],
192
- // 5. Hide whole facts. First a stale quota reading's age: it outlasts the
193
- // bar, the labels and the whitespace, so a laptop still sees that the
194
- // rates are old, and it goes before every other part of the pace left.
195
- // Then the burn rate and the reset time: the sign keeps the verdict,
196
- // and the target is the number to act on. The word
196
+ // 5. Hide whole facts. First the "sub" mark: that a model runs on your
197
+ // subscription is rarely news, so it is the least important fact, but
198
+ // it is still data and outlasts all the formatting above. Then a stale
199
+ // quota reading's age: it outlasts the bar, the labels and the
200
+ // whitespace, so a laptop still sees that the rates are old, and it
201
+ // goes before every other part of the pace left. Then the pace reading
202
+ // and the reset time: the sign keeps the verdict, and the target is
203
+ // the number to act on. The last message's "hit" or "miss" hides
204
+ // before the session hit rate: the session rate is the cost signal,
205
+ // and the last message only hints at it. The session rate also
206
+ // outlasts the token counts, which the context gauge already sums
207
+ // up, so a phone keeps one cache fact. The word
197
208
  // "target" outlasts the cache and token facts, because it names that
198
- // number once the burn rate is gone. The time left on the cache
209
+ // number once the pace reading is gone. The time left on the cache
199
210
  // outlasts it: it says whether to hurry back before a cold restart.
200
211
  // The cost per turn goes last of them, because seeing what each turn
201
212
  // costs is half of what the footer is for. The target rate hides only
202
213
  // at the very end, in step 7.
214
+ ["cost", "least"],
203
215
  ["pace", "brief"], ["pace", "bare"],
204
- ["reuse", "hidden"], ["cacheSession", "hidden"], ["tokens", "hidden"], ["pace", "least"], ["expiry", "hidden"], ["perTurn", "hidden"],
205
- // 6. Drop the cause of a cache miss, keeping its cost. It outranks every
206
- // hidden fact: it shows only on the turn that missed, and says what to
207
- // do about the cost (an idle gap or a model switch).
216
+ ["reuse", "hidden"], ["latest", "brief"], ["tokens", "hidden"], ["cacheSession", "hidden"], ["pace", "least"], ["expiry", "hidden"], ["perTurn", "hidden"],
217
+ // 6. Drop the cause of a detected cache miss, keeping its cost.
218
+ // Unlike a plain "hit" or "miss", it outranks every hidden fact: it
219
+ // shows only on the turn that missed, and says what to do about the
220
+ // cost (an idle gap or a model switch).
208
221
  ["latest", "bare"],
209
222
  // 7. Last, hide the target rate. Because the footer takes the fullest
210
223
  // state with the fewest lines, this fires only where the target alone
@@ -337,8 +350,14 @@ function formatTokens(n: number): string {
337
350
  return String(n);
338
351
  }
339
352
 
340
- function formatCost(value: number): string {
341
- return value < 0.1 ? value.toFixed(3) : value.toFixed(2);
353
+ /** A number with as many decimal places as its size earns: two below 10, one below 100, none from 100, and never more than maxPlaces.
354
+ * @example
355
+ * [formatDecimal(0.099), formatDecimal(9.996), formatDecimal(12.34), formatDecimal(99.96), formatDecimal(123.4), formatDecimal(5.25, 1)]
356
+ * // ["0.10", "10.0", "12.3", "100", "123", "5.3"]
357
+ */
358
+ function formatDecimal(value: number, maxPlaces = 2): string {
359
+ const places = [2, 1].find((candidate) => candidate <= maxPlaces && Number(value.toFixed(candidate)) < 10 ** (3 - candidate)) ?? 0;
360
+ return value.toFixed(places);
342
361
  }
343
362
 
344
363
  function currentDirectoryName(cwd: string): string {
@@ -563,20 +582,20 @@ function detectCacheMiss(previous: PreviousRequest | undefined, message: Assista
563
582
  };
564
583
  }
565
584
 
566
- /** The latest miss in its three forms. Ranked: what it cost, then why it
585
+ /** The last message's miss in its three forms. Ranked: what it cost, then why it
567
586
  * happened, then how many tokens. Without a cost, the tokens take its place.
568
587
  * @example
569
588
  * cacheMissForms({ missedTokens: 199_000, missedCost: 0.38, idleMs: 360_000, modelChanged: false })
570
- * // { full: "latest miss after 6m idle: 199k re-billed $0.38", short: "miss 6m idle $0.38", bare: "miss $0.38" }
589
+ * // { full: "miss after 6m idle: 199k re-billed $0.38", short: "miss 6m idle $0.38", bare: "miss $0.38" }
571
590
  */
572
591
  function cacheMissForms(miss: CacheMiss): Record<"full" | "short" | "bare", string> {
573
592
  // Pi's notice shows a cost from one cent, rounded to cents, and an idle gap from the TTL, in whole minutes.
574
- const cost = miss.missedCost >= 0.01 ? `$${miss.missedCost.toFixed(2)}` : null;
593
+ const cost = miss.missedCost >= 0.01 ? `$${formatDecimal(miss.missedCost)}` : null;
575
594
  const cause = miss.modelChanged ? "model switch" : miss.idleMs >= CACHE_TTL_MS ? `${Math.round(miss.idleMs / 60_000)}m idle` : null;
576
595
  const tokens = formatTokens(miss.missedTokens);
577
596
  const words = (...parts: (string | null)[]) => parts.filter(Boolean).join(" ");
578
597
  return {
579
- full: words("latest miss", cause && `after ${cause}:`, `${tokens} re-billed`, cost),
598
+ full: words("miss", cause && `after ${cause}:`, `${tokens} re-billed`, cost),
580
599
  short: words("miss", cause, cost ?? tokens),
581
600
  bare: words("miss", cost ?? tokens),
582
601
  };
@@ -1007,38 +1026,42 @@ export default function (pi: ExtensionAPI) {
1007
1026
  // A dirty worktree is a property of the place, not a cost, so it stays in
1008
1027
  // the place family and leaves `warning` meaning spend alone.
1009
1028
  const dirty = gitDirty ? paint.token(PLACE_TOKEN, "*") : "";
1010
- const gauge = paint.ramp(CONTEXT_STOPS, pct, `${ctxGauge(pct)} ${Math.round(pct)}%`);
1029
+ const gauge = paint.ramp(CONTEXT_STOPS, pct, `${ctxGauge(pct)}${Math.round(pct)}%`);
1011
1030
  // Colour the figure that moves and leave its reference quiet, so the eye
1012
1031
  // lands on the reading rather than on the window size beside it.
1013
1032
  const usedTokens = paint.ramp(CONTEXT_STOPS, pct, formatTokens(tokens));
1014
1033
  const usingSubscription = currentCtx.model
1015
1034
  ? currentCtx.modelRegistry?.isUsingOAuth?.(currentCtx.model)
1016
1035
  : false;
1017
- const cost = (amount: string) => paint.token(SPEND_TOKEN, `$${amount}`) + (usingSubscription ? theme.fg("muted", " sub") : "");
1036
+ const cost = (maxPlaces: number) => paint.token(SPEND_TOKEN, `$${formatDecimal(stats.totalCost, maxPlaces)}`);
1037
+ const sub = usingSubscription ? theme.fg("muted", " sub") : "";
1018
1038
  // A hit rate is a measurement, so it rides the ramp. The old cliff at 80%
1019
1039
  // made 79% and 20% look identical and threw the reading away.
1020
1040
  const sessionHit = stats.sessionCacheHitRate;
1021
1041
  const sessionHitText = sessionHit != null
1022
- ? paint.ramp(CACHE_STOPS, sessionHit, `${sessionHit.toFixed(1)}% session`)
1042
+ ? paint.ramp(CACHE_STOPS, sessionHit, `${formatDecimal(sessionHit, 1)}% session`)
1023
1043
  : theme.fg("dim", "no cache yet");
1044
+ // The last message is a hit or a miss by its cache share alone. A miss that pi's accounting
1045
+ // also detects shows its cost and cause instead of the share.
1024
1046
  const latestHit = stats.latestCacheHitRate;
1025
- const missForms = stats.latestCacheMiss && cacheMissForms(stats.latestCacheMiss);
1047
+ const isHit = latestHit != null && latestHit > CACHE_HIT_ABOVE_PERCENT;
1048
+ const missForms = !isHit && stats.latestCacheMiss ? cacheMissForms(stats.latestCacheMiss) : null;
1026
1049
  const paceForms = (reading: Pace): FactForms => {
1027
1050
  const dim = (text: string) => theme.fg("dim", text);
1028
1051
  const burnHeat = (text: string) => paint.ramp(PACE_STOPS, pacePosition(reading.burn, false), text);
1029
- const burn = burnHeat(`${reading.burn.toFixed(2)}×`);
1030
- const target = paint.ramp(PACE_STOPS, pacePosition(reading.target, true), `${reading.target.toFixed(2)}×`);
1052
+ const burn = burnHeat(`${formatDecimal(reading.burn)}×`);
1053
+ const target = paint.ramp(PACE_STOPS, pacePosition(reading.target, true), `${formatDecimal(reading.target)}×`);
1031
1054
  // The sign carries the verdict, and colour repeats it.
1032
1055
  const sign = reading.burn > reading.target ? theme.fg("error", ">") : dim("≤");
1033
1056
  const resets = formatRemaining(reading.resetsInMs);
1034
1057
  // A stale reading keeps showing, with its age until "brief", the form without it.
1035
1058
  const age = reading.ageMs > PACE_STALE_AFTER_MS ? dim(` · ${formatRemaining(reading.ageMs)} old`) : "";
1036
1059
  return {
1037
- full: `${label("burn")}${paceBar(reading.used, reading.elapsed, burnHeat, dim)} ${burn} ${sign} ${label("target")}${target}${dim(` · resets in ${resets}`)}${age}`,
1038
- short: `${label("burn")}${burn} ${sign} ${label("target")}${target}${dim(` · ${resets}`)}${age}`,
1039
- brief: `${label("burn")}${burn} ${sign} ${label("target")}${target}${dim(` · ${resets}`)}`,
1040
- bare: `${sign} ${label("target")}${target}`,
1041
- least: `${sign} ${target}`,
1060
+ full: `${label("pace")}${paceBar(reading.used, reading.elapsed, burnHeat, dim)} ${burn} ${sign} ${label("target")}${target}${dim(` · resets in ${resets}`)}${age}`,
1061
+ short: `${label("pace")}${burn} ${sign} ${label("target")}${target}${dim(` · ${resets}`)}${age}`,
1062
+ brief: `${label("pace")}${burn} ${sign} ${label("target")}${target}${dim(` · ${resets}`)}`,
1063
+ bare: `${label("pace")}${sign} ${label("target")}${dim("(")}${target}${dim(")")}`,
1064
+ least: `${label("pace")}${sign} ${target}`,
1042
1065
  };
1043
1066
  };
1044
1067
  const footerFacts: Partial<Record<FooterFact, FactForms>> = {
@@ -1051,16 +1074,18 @@ export default function (pi: ExtensionAPI) {
1051
1074
  full: `${usedTokens}${theme.fg("dim", ` / ${formatTokens(window)} tokens`)}`,
1052
1075
  short: `${usedTokens}${theme.fg("dim", ` / ${formatTokens(window)}`)}`,
1053
1076
  },
1054
- cost: { full: cost(formatCost(stats.totalCost)), short: cost(stats.totalCost.toFixed(1)), bare: cost(stats.totalCost.toFixed(0)) },
1055
- perTurn: { full: paint.quiet(SPEND_TOKEN, `$${formatCost(stats.averageCostPerTurn)}/turn`) },
1077
+ cost: { full: `${cost(2)}${sub}`, short: `${cost(1)}${sub}`, bare: `${cost(0)}${sub}`, least: cost(0) },
1078
+ perTurn: { full: paint.quiet(SPEND_TOKEN, `$${formatDecimal(stats.averageCostPerTurn)}/turn`) },
1056
1079
  cacheSession: { full: `${label("cache")}${sessionHitText}`, bare: sessionHitText },
1080
+ // "brief" is the step where a plain hit or miss hides; a detected miss stays to the end.
1057
1081
  latest: missForms
1058
- ? { full: theme.fg("error", missForms.full), short: theme.fg("error", missForms.short), bare: theme.fg("error", missForms.bare) }
1082
+ ? { full: theme.fg("error", missForms.full), short: theme.fg("error", missForms.short), brief: theme.fg("error", missForms.short), bare: theme.fg("error", missForms.bare) }
1059
1083
  : latestHit != null
1060
1084
  ? {
1061
- full: paint.ramp(CACHE_STOPS, latestHit, `latest ${latestHit.toFixed(1)}%`),
1062
- short: paint.ramp(CACHE_STOPS, latestHit, `latest ${Math.round(latestHit)}%`),
1063
- bare: paint.ramp(CACHE_STOPS, latestHit, `latest ${Math.round(latestHit)}%`),
1085
+ full: paint.ramp(CACHE_STOPS, latestHit, `${isHit ? "hit" : "miss"} ${Math.round(latestHit)}%`),
1086
+ short: paint.ramp(CACHE_STOPS, latestHit, isHit ? "hit" : "miss"),
1087
+ brief: "",
1088
+ bare: "",
1064
1089
  }
1065
1090
  : undefined,
1066
1091
  reuse: {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giladbarnea/pi-custom-footer",
3
- "version": "0.1.13",
3
+ "version": "0.1.15",
4
4
  "description": "Context, cache, cost, and loaded skills at a glance in Pi.",
5
5
  "type": "module",
6
6
  "license": "MIT",