feat: add reset time formatting (#1)

Add configurable reset-time rendering for provider, local, and UTC modes.

Wire the setting through state.json, CODEXBAR_RESET_TIME_FORMAT, the Waybar tooltip, and the GTK settings view. Keep provider output as the default for upgrade compatibility.

Also preserve cached provider snapshots when a requested provider returns empty, invalid, or errored output, so transient refresh failures do not make providers disappear from the tooltip.

Author: khaneliman

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Reset time format picker.** A new `resetTimeFormat` setting (`provider`,
+  `local`, or `utc`) controls how the "Resets ..." line in both the tooltip and
+  the popover is rendered. Provider keeps the upstream string as-is (default,
+  no behavior change on upgrade); Local reformats `resetsAt` in the system
+  timezone with an explicit TZ suffix; UTC does the same with a literal "UTC".
+  All three modes tier the format by proximity (today drops the date,
+  this-year drops the year). Configurable from the popover's Settings view,
+  via `~/.config/codexbar-waybar/state.json`, or per-instance with the
+  `CODEXBAR_RESET_TIME_FORMAT` env var. Useful when the provider's
+  description is timezone-ambiguous -- for example Codex emits `"7:10 AM"`
+  for a `resetsAt` that's actually in UTC.
+
 ## [0.2.1] — 2026-05-30
 
 ### Fixed

README.md

@@ -161,6 +161,7 @@ definition or your shell profile.
 | `CODEXBAR_PROVIDERS` | from `config.json` | Space-separated provider IDs to query, bypassing `~/.codexbar/config.json`. Set per-Waybar instance if you want different sets per monitor. |
 | `CODEXBAR_BAR_PROVIDER` | from `state.json` | Pin a specific provider's session/weekly to the bar regardless of state. Set to a provider ID, or unset for `Highest`. |
 | `CODEXBAR_ANTIGRAVITY_CREDS` | `~/.gemini/oauth_creds.json` | Path to the Antigravity Google OAuth creds (written by `agy login`) the wrapper feeds to the CLI. |
+| `CODEXBAR_RESET_TIME_FORMAT` | from `state.json` | Reset-time rendering mode: `provider` (use the provider's `resetDescription` as-is, default), `local` (reformat `resetsAt` in the system timezone with a TZ suffix), or `utc` (same tiering, in UTC). The popover's Settings view exposes the same toggle. |
 | `CODEXBAR_LAYER_SHELL_LIB` | auto-detected | Override path to `libgtk4-layer-shell.so` if your distro stashes it somewhere unusual. |
 | `XDG_CACHE_HOME` | `~/.cache` | Where `last.json` snapshots live. |
 | `XDG_DATA_HOME` | `~/.local/share` | Where provider icons live (under `codexbar-waybar/icons/`). |

codexbar-popup.py

@@ -12,6 +12,7 @@
 
 from __future__ import annotations
 
+import datetime
 import json
 import os
 import signal
@@ -378,6 +379,10 @@ def make_icon(pid: str, size: int = 18) -> Gtk.Widget | None:
 _RESET_SPACE_BEFORE_PAREN = re.compile(r"(?<=\S)\(")
 _RESET_SPACE_AFTER_COMMA = re.compile(r",(?=\S)")
 _RESET_SPACE_BEFORE_AMPM = re.compile(r"(?<=\d)(?=[AaPp][Mm]\b)")
+_RESET_STARTS_WITH_RESETS = re.compile(r"^[Rr]esets")
+_RESET_RELATIVE = re.compile(r"^[Rr]esets in ")
+
+RESET_FORMATS = ("provider", "local", "utc")
 
 
 def normalize_reset_description(text: str) -> str:
@@ -393,6 +398,61 @@ def normalize_reset_description(text: str) -> str:
     return text
 
 
+def current_reset_format(state: dict | None = None) -> str:
+    """Resolve the active reset time format. Env var overrides state.json;
+    unknown values fall back to `provider` (current behavior)."""
+    env = os.environ.get("CODEXBAR_RESET_TIME_FORMAT")
+    if env in RESET_FORMATS:
+        return env
+    if state is None:
+        state = load_state()
+    value = state.get("resetTimeFormat")
+    return value if value in RESET_FORMATS else "provider"
+
+
+def _from_description(desc: str) -> str:
+    if not desc:
+        return ""
+    return desc if _RESET_STARTS_WITH_RESETS.match(desc) else f"Resets {desc}"
+
+
+def format_reset_label(window: dict, mode: str) -> str:
+    """Render the reset label for a usage window in the chosen format.
+
+    Mirrors `reset_phrase` in codexbar.sh so the popover and tooltip never
+    drift. Returns a string like "Resets 6:12 PM CDT" or "" for no info.
+    Relative phrases ("Resets in 2 hours") are preserved even in absolute
+    modes, since "in 2 hours" is more useful than a wall-clock time.
+    """
+    clean = normalize_reset_description(window.get("resetDescription") or "")
+    from_desc = _from_description(clean)
+    if mode == "provider":
+        return from_desc
+    if _RESET_RELATIVE.match(clean):
+        return from_desc
+    resets_at = window.get("resetsAt")
+    if not resets_at:
+        return from_desc
+    try:
+        ts = datetime.datetime.fromisoformat(resets_at.replace("Z", "+00:00"))
+    except (TypeError, ValueError):
+        return from_desc
+    if mode == "utc":
+        ts = ts.astimezone(datetime.timezone.utc)
+        tz_suffix = "UTC"
+    else:
+        ts = ts.astimezone()
+        tz_suffix = ts.tzname() or ""
+    now = datetime.datetime.now(ts.tzinfo)
+    if ts.date() == now.date():
+        body = ts.strftime("%-I:%M %p")
+    elif ts.year == now.year:
+        body = ts.strftime("%b %-d at %-I:%M %p")
+    else:
+        body = ts.strftime("%b %-d %Y at %-I:%M %p")
+    return f"Resets {body} {tz_suffix}".rstrip()
+
+
 def fetch_fresh() -> list:
     try:
         subprocess.run([str(WRAPPER)], check=False, capture_output=True, timeout=30)
@@ -701,6 +761,22 @@ def _render_settings_body(self):
         # Divider between sections.
         self.body.append(self._divider())
 
+        # --- Section: reset time format ---
+        reset_title = Gtk.Label(label="Reset times", xalign=0.0)
+        reset_title.add_css_class("codexbar-section-title")
+        self.body.append(reset_title)
+        reset_hint = Gtk.Label(
+            label="How to render the “Resets …” label. Provider keeps the raw "
+                  "string each backend emits; Local/UTC reformat the reset "
+                  "timestamp with an explicit timezone.",
+            xalign=0.0, wrap=True, max_width_chars=44)
+        reset_hint.add_css_class("codexbar-subtitle")
+        self.body.append(reset_hint)
+        self.body.append(self._build_reset_format_picker())
+
+        # Divider between sections.
+        self.body.append(self._divider())
+
         # --- Section: enabled providers ---
         section_title = Gtk.Label(label="Providers", xalign=0.0)
         section_title.add_css_class("codexbar-section-title")
@@ -779,6 +855,36 @@ def _on_bar_provider_change(self, pid: str | None):
         # Nudge waybar so the bar text updates immediately.
         subprocess.Popen(["pkill", "-RTMIN+8", "waybar"])
 
+    def _build_reset_format_picker(self) -> Gtk.Widget:
+        wrap = Gtk.FlowBox()
+        wrap.add_css_class("codexbar-bar-picker")
+        wrap.set_selection_mode(Gtk.SelectionMode.NONE)
+        wrap.set_homogeneous(False)
+        wrap.set_max_children_per_line(8)
+        current = current_reset_format()
+        labels = (("provider", "Provider"), ("local", "Local"), ("utc", "UTC"))
+        for value, label in labels:
+            classes = ["codexbar-tab"]
+            if value == current:
+                classes.append("active")
+            wrap.append(self._make_pill(
+                label, classes,
+                lambda v=value: self._on_reset_format_change(v)))
+        return wrap
+
+    def _on_reset_format_change(self, value: str):
+        state = load_state()
+        if value == "provider":
+            state.pop("resetTimeFormat", None)
+        else:
+            state["resetTimeFormat"] = value
+        save_state(state)
+        # Re-render the Settings view so the chip highlight tracks the click,
+        # and signal waybar so the tooltip picks up the new format on its
+        # next refresh.
+        self.render()
+        subprocess.Popen(["pkill", "-RTMIN+8", "waybar"])
+
     def _settings_row(self, pid: str, enabled: bool, *, enabled_ui: bool) -> Gtk.Widget:
         row = Gtk.Box(orientation=Gtk.Orientation.HORIZONTAL, spacing=10)
         row.add_css_class("codexbar-settings-row")
@@ -925,9 +1031,8 @@ def _section(self, title: str, window: dict) -> Gtk.Widget:
         left.add_css_class("codexbar-section-detail-left")
         details.append(left)
 
-        reset = normalize_reset_description(window.get("resetDescription") or "")
-        if reset:
-            reset_text = reset if reset.lower().startswith("reset") else f"Resets {reset}"
+        reset_text = format_reset_label(window, current_reset_format())
+        if reset_text:
             r = Gtk.Label(label=reset_text, xalign=1.0)
             r.add_css_class("codexbar-section-detail-right")
             details.append(r)

codexbar.sh

@@ -23,10 +23,25 @@ mkdir -p "$CACHE_DIR"
 # Per-instance bar provider selection (written by the popup's Settings view).
 # `null` (or unset) means "show the highest used% across providers".
 BAR_PROVIDER=""
+# How to render reset times in the tooltip / popover:
+#   provider — use the provider's `resetDescription` as-is (default; backward
+#              compatible — Claude OAuth gives "May 17 at 6:20AM" with no TZ,
+#              Codex gives "7:10 AM" in UTC with no TZ marker, etc.)
+#   local    — format `resetsAt` (ISO 8601 UTC) in the system local timezone
+#              with a today / this-year / future-year tier and a TZ suffix
+#   utc      — same tiering, formatted in UTC with a literal "UTC" suffix
+RESET_TIME_FORMAT="provider"
 if [[ -f "$STATE_PATH" ]] && command -v jq >/dev/null 2>&1; then
     BAR_PROVIDER="$(jq -r '.barProvider // empty' "$STATE_PATH" 2>/dev/null)"
+    rf="$(jq -r '.resetTimeFormat // empty' "$STATE_PATH" 2>/dev/null)"
+    [[ -n "$rf" ]] && RESET_TIME_FORMAT="$rf"
 fi
 [[ -n "${CODEXBAR_BAR_PROVIDER:-}" ]] && BAR_PROVIDER="$CODEXBAR_BAR_PROVIDER"
+[[ -n "${CODEXBAR_RESET_TIME_FORMAT:-}" ]] && RESET_TIME_FORMAT="$CODEXBAR_RESET_TIME_FORMAT"
+case "$RESET_TIME_FORMAT" in
+    provider|local|utc) ;;
+    *) RESET_TIME_FORMAT="provider" ;;
+esac
 
 # Read enabled providers from the codexbar CLI's config, fall back to a
 # sensible default if it's missing or unreadable. Override with the
@@ -204,27 +219,52 @@ for p in "${PROVIDERS[@]}"; do
 done
 merged+="]"
 
-# Fill in errored providers with the last successful snapshot (marks them stale).
-if [[ -f "$LAST_GOOD" ]] && [[ "$merged" != "[]" ]]; then
-    merged="$(jq -c --argjson prev "$(cat "$LAST_GOOD")" '
+# Persist fresh successful provider snapshots without dropping older successful
+# entries for providers that failed this refresh.
+if [[ "$merged" != "[]" ]] && echo "$merged" | jq -e 'any(.error | not)' >/dev/null 2>&1; then
+    if [[ -f "$LAST_GOOD" ]]; then
+        merged_for_cache="$(jq -c --argjson prev "$(cat "$LAST_GOOD")" '
+            ([$prev[]? | select((.error | not) and (.stale != true))
+              | {key: .provider, value: .}] | from_entries) as $ok_prev
+            | ([.[]? | select(.error | not)
+              | {key: .provider, value: (del(.stale))}] | from_entries) as $ok_fresh
+            | ($ok_prev + $ok_fresh) | [.[]]
+        ' <<< "$merged")"
+        echo "$merged_for_cache" > "$LAST_GOOD"
+    else
+        echo "$merged" | jq -c 'map(select(.error | not) | del(.stale))' > "$LAST_GOOD"
+    fi
+fi
+
+# Fill in errored or missing providers with the last successful snapshot for
+# display (marks them stale). Missing happens when a provider returns
+# empty/invalid output instead of a JSON array.
+if [[ -f "$LAST_GOOD" ]]; then
+    providers_json="$(printf '%s\n' "${PROVIDERS[@]}" | jq -R . | jq -s .)"
+    merged="$(jq -c \
+        --argjson prev "$(cat "$LAST_GOOD")" \
+        --argjson requested "$providers_json" '
         ([$prev[]? | select(.error | not) | {key: .provider, value: .}] | from_entries) as $ok_prev
+        | (map(.provider) | unique) as $seen
         | map(if .error and $ok_prev[.provider]
               then $ok_prev[.provider] + {stale: true}
-              else . end)
+              else . end) as $current
+        | ($requested
+           | map(. as $pid | select(($seen | index($pid)) | not))
+           | map($ok_prev[.]? | select(. != null) + {stale: true})) as $missing
+        | $current + $missing
     ' <<< "$merged")"
 fi
 
-# Persist snapshot if at least one provider succeeded.
-if [[ "$merged" != "[]" ]] && echo "$merged" | jq -e 'any(.error | not)' >/dev/null 2>&1; then
-    echo "$merged" > "$LAST_GOOD"
-fi
-
 if [[ "$merged" == "[]" ]]; then
     printf '{"text":"","tooltip":"CodexBar: no provider data","class":"stale","percentage":0}\n'
     exit 0
 fi
 
-echo "$merged" | jq -c --arg now "$(date -u +%FT%TZ)" --arg bar_provider "$BAR_PROVIDER" '
+echo "$merged" | jq -c \
+    --arg now "$(date -u +%FT%TZ)" \
+    --arg bar_provider "$BAR_PROVIDER" \
+    --arg reset_format "$RESET_TIME_FORMAT" '
     # Collect all usage windows across providers
     def provider_name(p):
         {codex:"Codex", claude:"Claude", gemini:"Gemini",
@@ -242,16 +282,54 @@ echo "$merged" | jq -c --arg now "$(date -u +%FT%TZ)" --arg bar_provider "$BAR_P
         | gsub(",(?=\\S)"; ", ")
         | gsub("(?<=\\d)(?=[AaPp][Mm]\\b)"; " ");
 
-    def reset_phrase(d):
-        if d == null then ""
-        else (d | normalize_reset) as $clean
-             | if ($clean | test("^[Rr]esets")) then " — \($clean)"
-               else " — resets \($clean)" end
+    # Format a UNIX timestamp in the system local timezone, tiered by how far
+    # away the reset is. Today drops the date; this year drops the year.
+    def fmt_local_ts:
+        . as $ts
+        | ($ts | strflocaltime("%Y-%m-%d")) as $rd
+        | (now | strflocaltime("%Y-%m-%d")) as $td
+        | ($ts | strflocaltime("%Y")) as $ry
+        | (now | strflocaltime("%Y")) as $cy
+        | if $rd == $td then ($ts | strflocaltime("%-I:%M %p %Z"))
+          elif $ry == $cy then ($ts | strflocaltime("%b %-d at %-I:%M %p %Z"))
+          else ($ts | strflocaltime("%b %-d %Y at %-I:%M %p %Z")) end;
+
+    # Same tiering, formatted in UTC. We hardcode the "UTC" suffix because
+    # `strftime("%Z")` after `gmtime` is empty on some libc builds.
+    def fmt_utc_ts:
+        . as $ts
+        | ($ts | gmtime | strftime("%Y-%m-%d")) as $rd
+        | (now | gmtime | strftime("%Y-%m-%d")) as $td
+        | ($ts | gmtime | strftime("%Y")) as $ry
+        | (now | gmtime | strftime("%Y")) as $cy
+        | if $rd == $td then ($ts | gmtime | strftime("%-I:%M %p UTC"))
+          elif $ry == $cy then ($ts | gmtime | strftime("%b %-d at %-I:%M %p UTC"))
+          else ($ts | gmtime | strftime("%b %-d %Y at %-I:%M %p UTC")) end;
+
+    # Build the trailing " — resets …" fragment for a usage window. Mode is
+    # one of "provider" (preserve the provider string), "local", or "utc".
+    # Relative phrases like "Resets in 2 hours" are kept verbatim even in
+    # absolute modes — "in 2 hours" is more useful than a wall-clock time.
+    def reset_phrase(w):
+        if w == null then ""
+        else (w.resetDescription // "" | normalize_reset) as $clean
+             | (if $clean == "" then ""
+                elif ($clean | test("^[Rr]esets")) then " — \($clean)"
+                else " — resets \($clean)" end) as $from_desc
+             | if $reset_format == "provider" then $from_desc
+               elif ($clean | test("^[Rr]esets in ")) then $from_desc
+               elif w.resetsAt != null then
+                   (try (w.resetsAt | fromdateiso8601) catch null) as $ts
+                   | if $ts == null then $from_desc
+                     elif $reset_format == "utc" then " — resets \($ts | fmt_utc_ts)"
+                     else " — resets \($ts | fmt_local_ts)" end
+               else $from_desc
+               end
         end;
 
     def fmt_window(w; name):
         if w == null or w.usedPercent == null then empty
-        else "\(name): \(w.usedPercent)%" + reset_phrase(w.resetDescription)
+        else "\(name): \(w.usedPercent)%" + reset_phrase(w)
         end;
 
     def provider_lines(entry):