Prompt cache line ignores display.timeFormat — no relative/minutes-remaining option

Author: cjangristCreated Sep 3, 2026Updated Sep 3, 2026

Summary

The prompt cache line (src/render/lines/prompt-cache.ts) hardcodes formatAbsoluteTime() for its value and never consults display.timeFormat. Every other clock-bearing element in the HUD (usage windows, via usage.ts) goes through the shared formatResetTime() helper in format-reset-time.ts, which already supports 'relative' | 'absolute' | 'both'. Prompt cache is the one element that can't use it.

Confirmed on the installed 0.8.0 build:

typescript
// prompt-cache.ts
const value = state === 'expired'
  ? t('status.expired')
  : formatAbsoluteTime(expiresAt, new Date(now), wallClockOpts, 'format.untilTime');

vs. usage.ts, which reads display.timeFormat and calls the shared formatResetTime()/formatWindowTime() path.

Problem to Solve

There's no way to see "X minutes until the prompt cache expires" — only a wall-clock time (Cache ⏱ until 3:00 AM). This was originally requested as a countdown in #400, closed in favor of the current absolute-time rendering, with this rationale in the source comment:

Expiry time rather than a countdown: the statusline only repaints while Claude Code is active, so between turns — exactly when the cache is draining — a countdown freezes at whatever it last displayed and keeps reporting it. A clock time stays true however stale the render is.

Two things have since changed that reasoning:

  1. #727 already proposed the fix that preserves this guarantee ("Option 2" in that issue) — let the prompt-cache line honor display.timeFormat the same way usage.ts does, so 'both' mode yields Cache ⏱ 57m, at 12:16 PM. The absolute time stays authoritative and stale-safe exactly as today; the relative part only ever understates remaining time on a stale render, which is the safe direction (this is explicitly noted in #727 itself). #727 shipped the minimal fix (explicit "until" wording) but not this option.
  2. refreshInterval (settings.json) now exists, letting the HUD repaint on a timer independent of turns. With refreshInterval: 1 set, the staleness concern in the original comment doesn't apply at all — the prompt-cache line could safely support a 'relative'-only mode too, ticking live just like a real countdown, for anyone who opts into a refresh timer.

Proposed Solution

Make renderPromptCacheLine() route through the existing formatResetTime() (or an equivalent) instead of calling formatAbsoluteTime() directly, honoring display.timeFormat:

  • 'absolute' (current/default behavior) — Cache ⏱ until 3:00 AM
  • 'relative'Cache ⏱ 58m
  • 'both'Cache ⏱ 58m, until 3:00 AM

This reuses code that already exists and is already tested for the usage line — no new formatting logic needed, just wiring prompt-cache.ts up to the same helper usage.ts uses.

Alternatives Considered

Reverting fully to a countdown-only display, as in the original #400 — rejected for the same reason it was rejected there when no refreshInterval is set. Making timeFormat the only control (Option 2 from #727) rather than a separate countdown mode threads this correctly: users who want absolute-only keep exactly today's behavior by default.

Additional Context

Reproduced on claude-hud 0.8.0, Claude Code 2.1.258, Node 24.18.1, Linux. Related: #400, #727, #719, #725 (per-window timeFormat, same underlying config key this would extend).