clauddy 1.17.1 → 1.18.0

package/README.md

@@ -177,7 +177,19 @@ Switching is instant — no restart. (On Windows/Linux the icon lives in the sys
 
 ## Alerts
 
-Optional **macOS notifications** when your session or weekly usage crosses the thresholds you set (default **80%** and **95%**) — e.g. _"Your session is over 80% — now at 82%"_. They re-arm automatically once usage drops back below a threshold (after a reset). Toggle them and edit the thresholds in **⚙ Settings**.
+Optional **macOS notifications**, toggled (with their thresholds) in **⚙ Settings**:
+
+| Notification | When |
+| --- | --- |
+| _Session at 82%_ — `2h 39m left · resets 6:50 PM` | Your session crosses a threshold (default **80%** and **95%**) |
+| _Weekly usage at 84%_ — `resets Fri 7:00 AM` | Same, for the weekly limit |
+| _Fable weekly at 84%_ — `resets Fri 7:00 AM` | Same, for a per-model weekly limit |
+| _Session window reset_ — `full budget again` | A session you had pushed past 80% rolls over |
+| _Clauddy lost access to your usage_ | The OAuth token expired or was revoked, so the % went back to being an estimate |
+
+The last threshold you set is the only one that makes a sound; the earlier ones arrive silently. Clicking any of them brings the widget to the front. Each fires once and re-arms when usage drops back below — remembered across restarts, so relaunching at 85% doesn't repeat an alert you already dismissed.
+
+Percentages come from your account when you're logged in, and fall back to the local token estimate when you're not.
 
 The first alert asks macOS for permission; after that the app shows up in **System Settings > Notifications** like any other.
 

package/main.js

@@ -52,6 +52,7 @@ let currentMode = 'floating' // 'floating' widget | 'menubar' popover
 let trayBounds = null // last known tray icon rect, to anchor the popover
 let lastBlurHide = 0 // debounce: ignore the tray click that dismissed the popover
 let sessionPct = null // authoritative session % shown in the tray title
+let realUsage = null // last OAuth usage payload — the % alerts trust when logged in
 let lastProgrammaticMove = 0 // ignore the 'moved' event our own setPosition triggers
 let displayChanging = 0 // ignore OS window-shuffles while a display (dis)connects
 
@@ -92,46 +93,133 @@ function loadConfig() {
   return defaults
 }
 
-// native notification when usage crosses a threshold
-const armed = new Set()
-function checkAlerts(config, d) {
-  alertScopes(config, [
-    ['session', d.session.pct],
-    ['weekly usage', d.week.pct],
-  ])
+// ---- alerts ------------------------------------------------------------------
+// One notification per (scope × threshold), re-armed when usage drops back below.
+// `armed` is persisted so relaunching at 85% doesn't repeat the 80% alert you
+// already dismissed; it also carries the last session % so a reset is detectable
+// across restarts.
+const ALERTS_FILE = path.join(DATA_DIR, 'alerts.json')
+let armed = new Set()
+let lastSessionPct = null
+function loadAlertState() {
+  try {
+    const j = JSON.parse(fs.readFileSync(ALERTS_FILE, 'utf8'))
+    armed = new Set(Array.isArray(j.armed) ? j.armed : [])
+    lastSessionPct = typeof j.lastSessionPct === 'number' ? j.lastSessionPct : null
+  } catch {} // first run, or a corrupted file: start from a clean slate
 }
-// per-model weekly limits only exist on the account side, so they're checked
-// off the OAuth poll rather than the local tick
-function checkScopedAlerts(config, u) {
-  alertScopes(
-    config,
-    (u?.scoped || []).map((s) => [`${s.label} weekly usage`, s.pct]),
-  )
+function saveAlertState() {
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true })
+    fs.writeFileSync(ALERTS_FILE, JSON.stringify({ armed: [...armed], lastSessionPct }))
+  } catch {}
+}
+
+function fmtDuration(ms) {
+  const h = Math.floor(ms / 3600000)
+  const m = Math.floor((ms % 3600000) / 60000)
+  return h > 0 ? `${h}h ${m}m` : `${m}m`
+}
+// wall-clock time the window flips, in the machine's own locale + timezone
+function fmtClock(ms) {
+  const at = new Date(Date.now() + ms)
+  const time = at.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
+  return ms >= 86400000 ? `${at.toLocaleDateString([], { weekday: 'short' })} ${time}` : time
 }
+
+function notify(title, body, { silent = true } = {}) {
+  if (!Notification.isSupported()) return
+  const n = new Notification({ title, body, silent })
+  n.on('click', showWidget) // the obvious gesture: bring the pet to the front
+  n.show()
+}
+
+// the alert lines carry the reset, since "what do I do about it" is a question
+// about time left, not about the threshold that happened to fire
+function resetLine(resetMs, withRemaining) {
+  if (resetMs == null) return ''
+  const at = `resets ${fmtClock(resetMs)}`
+  return withRemaining && resetMs > 0 ? `${fmtDuration(resetMs)} left · ${at}` : at
+}
+
+// usage crossing a threshold. `scopes` are {label, pct, resetMs, session} rows;
+// the real (OAuth) numbers are preferred over the local token estimate, which is
+// only a budget guess and can be off by an order of magnitude.
 function alertScopes(config, scopes) {
-  if (!config.alerts || !Notification.isSupported()) return
+  if (!config.alerts) return
   const ths = config.alertThresholds || [80, 95]
-  for (const [name, pct] of scopes) {
+  const top = Math.max(...ths)
+  let dirty = false
+  for (const { label, pct, resetMs, session } of scopes) {
+    if (pct == null) continue
     for (const t of ths) {
-      const key = `${name}:${t}`
+      const key = `${label}:${t}`
       if (pct >= t) {
         if (!armed.has(key)) {
           armed.add(key)
-          new Notification({
-            title: 'Clauddy',
-            body: `Your ${name} is over ${t}% — now at ${Math.round(pct)}%`,
-            silent: false,
-          }).show()
+          dirty = true
+          const urgent = t === top
+          notify(
+            `${label} at ${Math.round(pct)}%${urgent ? ' — almost out' : ''}`,
+            resetLine(resetMs, session),
+            { silent: !urgent }, // 80% is a heads-up; the last threshold earns a sound
+          )
         }
-      } else {
-        armed.delete(key) // re-arm when it drops below
+      } else if (armed.delete(key)) {
+        dirty = true // re-arm when it drops below
       }
     }
   }
+  if (dirty) saveAlertState()
+}
+
+function checkAlerts(config, d) {
+  const r = realUsage // authoritative when logged in; the estimate is the fallback
+  const session = r?.session ?? d.session
+  const week = r?.week ?? d.week
+  alertScopes(config, [
+    { label: 'Session', pct: session.pct, resetMs: session.resetMs, session: true },
+    { label: 'Weekly usage', pct: week.pct, resetMs: week.resetMs },
+  ])
+  checkWindowReset(config, session.pct)
+}
+// per-model weekly limits only exist on the account side, so they're checked
+// off the OAuth poll rather than the local tick
+function checkScopedAlerts(config, u) {
+  alertScopes(
+    config,
+    (u?.scoped || []).map((s) => ({
+      label: `${s.label} weekly`,
+      pct: s.pct,
+      resetMs: s.resetMs,
+    })),
+  )
+}
+
+// "you can work again" — only worth saying to someone who was actually near the
+// ceiling, so a window flipping at 20% stays silent
+const RESET_FROM = 80
+const RESET_TO = 5
+function checkWindowReset(config, pct) {
+  if (pct == null) return
+  const was = lastSessionPct
+  lastSessionPct = pct
+  if (config.alerts && was != null && was >= RESET_FROM && pct <= RESET_TO) {
+    notify('Session window reset', 'full budget again')
+  }
+  if (was == null || Math.round(was) !== Math.round(pct)) saveAlertState()
+}
+
+// the token going dead is a silent failure otherwise: the widget quietly falls
+// back to the local estimate and keeps showing a number the user trusts
+function alertAuthLost(config) {
+  if (!config.alerts) return
+  notify('Clauddy lost access to your usage', 'open Settings to reconnect')
 }
 
 function createWindow() {
   config = loadConfig()
+  loadAlertState()
   const { workAreaSize } = screen.getPrimaryDisplay()
   const H = 480
 
@@ -289,6 +377,16 @@ function showPopover() {
   win.focus()
 }
 
+// bring the widget to the front from wherever it is, in either mode
+function showWidget() {
+  if (!win || win.isDestroyed()) return
+  if (currentMode === 'menubar') showPopover()
+  else {
+    win.show()
+    win.focus()
+  }
+}
+
 // route every programmatic move through here so the 'moved' handler can tell
 // our own repositioning apart from a genuine user drag (and skip saving it)
 function moveWindow(x, y) {
@@ -369,6 +467,7 @@ function updateTray() {
 
 // send real usage to the renderer and refresh the tray title in one place
 function pushRealUsage(u) {
+  realUsage = u
   sessionPct = u?.session ? u.session.pct : null
   updateTray()
   checkScopedAlerts(config, u)
@@ -428,6 +527,7 @@ async function pollUsage() {
     } else if (e && e.status === 401) {
       auth.clear()
       pushRealUsage(null)
+      alertAuthLost(config)
       if (win && !win.isDestroyed()) {
         win.webContents.send('auth-state', { connected: false })
         win.webContents.send('profile', null)
@@ -503,8 +603,14 @@ ipcMain.on('save-config', (_e, patch) => {
     fs.mkdirSync(path.dirname(EXTERNAL_CONFIG), { recursive: true })
     fs.writeFileSync(EXTERNAL_CONFIG, JSON.stringify(obj, null, 2))
   } catch {}
+  const prevThresholds = String(config.alertThresholds)
   config = loadConfig()
-  armed.clear() // re-arm alerts with new thresholds
+  // re-arm only when the thresholds actually moved: saving an unrelated setting
+  // (zoom, mode…) shouldn't replay an alert the user already dismissed
+  if (String(config.alertThresholds) !== prevThresholds) {
+    armed.clear()
+    saveAlertState()
+  }
   if (doTick) doTick()
   if (win && !win.isDestroyed()) win.webContents.send('config', publicConfig(config))
   applyMode(config.mode) // switch between floating widget and menu-bar popover live

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clauddy",
   "desktopName": "clauddy.desktop",
-  "version": "1.17.1",
+  "version": "1.18.0",
   "description": "A cute desktop pet that tracks your Claude Code usage",
   "main": "main.js",
   "bin": {