clauddy 1.24.0 → 1.26.0

package/README.md

@@ -109,6 +109,35 @@ Other activities — **planning**, **researching**, **delegating**, **waiting**
 show up in the status line as they happen. When Claude goes quiet, the pet drops
 back to plain **working** / **idle**.
 
+## The pet talks
+
+Now and then the pet says something in a speech bubble. It only speaks when something changes, never on a timer, and it keeps quiet when it has nothing specific to say. Remarks are at least 10 minutes apart; the big moments can cut that line.
+
+| Moment | What it says (expanded) | Minimized | Blip |
+| --- | --- | --- | --- |
+| First launch of the day | _Good morning! Yesterday was your heaviest day this week, 12M tokens._ | _Morning! Big day yesterday._ | ✓ |
+| Session crosses your fire threshold | _Getting warm, 91% already. At this pace you'll run out in about 40m._ | _91%, getting warm!_ | ✓ |
+| The session window resets | _Fresh window! That was 34M tokens over 4h 12m, mostly editing code._ | _Fresh window! 34M last time._ | ✓ |
+| The session hits 100% | _That's the limit. I'll be back at 2:35 PM._ | _Maxed out till 2:35 PM._ | |
+| You're back after 2+ hours away | _Welcome back! You were gone 3h 12m. The session's at 12%._ | _Welcome back!_ | |
+| 90 minutes of unbroken work | _You've been at it for 1h 35m straight. Stretch break?_ | _Stretch break?_ | |
+| A new record day (30-day best) | _New record! 45M tokens today, your biggest day in a month._ | _New record: 45M!_ | |
+| Codex crosses fire, hits 100%, or resets | _Codex is at 91% now. It resets in 1h 12m._ | _Codex at 91%!_ | ✓ (fire, reset) |
+
+The greeting follows your clock (_Good morning_, _Good afternoon_, _Good evening_, or _Still up?_ before 5 AM) and appears once a day, and so does the record. The reset recap covers only what the pet actually saw, so if you launch it mid-session it says less. Click the bubble to dismiss it.
+
+### The voice
+
+Optionally the pet also **blips** as it talks: short chiptune notes, one per letter, generated live with Web Audio (square waves, no sound files). It blips faster and higher when it's on fire, slower and lower when it's sleepy. Only the headline moments blip (the ✓ rows above), because a sound on every remark wears out fast.
+
+Audio should never catch you off guard in a meeting:
+
+- **Off by default.** Turn it on under **⚙ Settings → voice → Chiptune voice** (you'll hear a sample).
+- **One-click mute.** While the voice is on, a 🔊 button sits in the title bar. Click it to mute for an hour, and again to unmute.
+- **Always silent** in menu-bar mode and while the pet is minimized.
+
+**Speech bubbles** can be switched off entirely in the same place. Try any remark from the terminal with `bunx clauddy say <kind>` ([see below](#play-with-the-pet)).
+
 ## Install
 
 **macOS (Apple Silicon)** is the first-class build. **Windows (x64)** and **Linux (x64)** work too. The `bunx`/`npx` route below runs on all of them today.
@@ -186,6 +215,7 @@ update-desktop-database ~/.local/share/applications 2>/dev/null
 
 - **Drag** the widget anywhere on screen
 - **–** minimizes to just the pet, ringed by the live session % (the number sits inside the ring) — or, with Claude and Codex both connected, one reading per service; the **⤢** button or a double-click on the pet expands it back
+- **Pet icon** in the compact header switches to **Just the pet** (floating mode). Drag the pet itself to move it. Hovering over the pet (or focusing it) reveals the usage glance; the small expand button in it returns to compact. Keyboard users can focus the pet and press Enter. The chosen size is remembered. In compact and pet-only modes, the pet follows whoever is working, with provider logos identifying Claude, Codex, or both. Usage selection stays manual; when neither is active the pet rests.
 - **⚙** opens settings (log in, toggle alerts, set thresholds, pick the display mode)
 - **↗** opens the official Usage page of the service on screen
 - **×** quits
@@ -199,6 +229,10 @@ Under **⚙ Settings → Preferences** you can pick where Clauddy lives:
 
 Switching is instant — no restart. (On Windows/Linux the icon lives in the system tray; the live % shows in its tooltip.)
 
+### Provider reactions
+
+When a provider's activity changes, the pet briefly glances toward it, with no caption. Both can be working at once. A glance never changes your selected provider, and glances share a 30-second cooldown. Inactivity is treated as a pause, not a completed task.
+
 ## Alerts
 
 Optional **macOS notifications**, toggled (with their thresholds) in **⚙ Settings**:
@@ -218,6 +252,12 @@ Percentages come from your account when you're logged in, and fall back to the l
 
 The first alert asks macOS for permission; after that the app shows up in **System Settings > Notifications** like any other.
 
+### Remind me at the session reset
+
+When the selected session crosses your first alert threshold, **Notify at reset** appears beneath the session details and in the compact monitor. Click to arm it; click **Reminder on** to cancel. This is a one-shot request, independent of the automatic threshold-alert toggle.
+
+Reminders survive restarts, belong to the Claude account or Codex connection that created them, and are canceled when you disconnect that source. Clauddy must be running to notify; an overdue reminder is delivered on reopening or waking up. A fresh, lower reading confirms that session budget returned and the pet celebrates. If usage hasn't refreshed — common with idle Codex logs — the reminder only says the scheduled reset time arrived and asks you to check usage.
+
 ## Configure (`config.json`)
 
 Settings saved from the UI live in `~/.claude-usage-monitor/config.json`, so you can tweak them without rebuilding:
@@ -232,6 +272,9 @@ Settings saved from the UI live in `~/.claude-usage-monitor/config.json`, so you
   "activeThresholdMs": 20000, // "active" if Claude wrote to its logs within this window
   "sleepThresholdMs": 300000, // "sleeping" after this much idle time (5 min)
   "codex": { "enabled": false }, // set by Settings → Codex → Connect
+  "talk": true, // speech bubbles on transitions
+  "sound": false, // chiptune blips, opt-in
+  "soundMutedUntil": 0, // set by the 🔊 button: muted until this epoch ms
 }
 ```
 
@@ -248,6 +291,8 @@ bunx clauddy working     # 🍴 eats token coins
 bunx clauddy tired       # 🥵 maxed out
 bunx clauddy idle        # 🙂 calm
 bunx clauddy auto        # ↩️ back to your real usage
+bunx clauddy say         # 💬 a remark in the speech bubble
+bunx clauddy say fire    #    or a specific one: greeting, fire, reset, maxed, welcome, streak, record, codex
 ```
 
 Each state is written to the data dir the running widget watches, so it reacts
@@ -259,7 +304,7 @@ live. (Installed globally? Drop the `bunx`: `clauddy poke`. Working on the repo?
 - **`main.js`** — Electron main process: frameless, transparent, always-on-top window; polls usage; fires macOS notifications; watches `config.json` and `debug.json`.
 - **`usage.js`** — reads `~/.claude/projects/**/*.jsonl`, sums tokens per model/project/day, detects the rolling 5-hour session window, the working/sleeping status, and which activity (reading/editing/running/…) Claude is on from its latest tool use.
 - **`auth.js`** — OAuth login (PKCE, same public client as Claude Code) that fetches the authoritative usage %. Token stored locally, never committed.
-- **`renderer/`** — the pet itself: an SVG pixel sprite, CSS animations, and the Web Animations API for particles.
+- **`renderer/`** — the pet itself: an SVG pixel sprite, CSS animations, and the Web Animations API for particles. `voice.js` writes its remarks and synthesizes the blips.
 - **`make-icon.js`** — generates the app icon from the pixel sprite (`build/icon.icns`).
 
 ## Data & privacy

package/bin/clauddy.js

@@ -20,6 +20,7 @@ const STATES = [
   'idle',
   'poke',
   'celebrate',
+  'say',
   'auto',
   'clear',
   // activity states (what Claude Code is doing)
@@ -31,7 +32,10 @@ const STATES = [
   'delegating',
   'waiting',
 ]
+// `clauddy say <kind>` previews one of the pet's remarks
+const REMARKS = ['greeting', 'fire', 'reset', 'maxed', 'welcome', 'streak', 'record', 'codex']
 const arg = process.argv[2]
+const kind = arg === 'say' ? process.argv[3] || 'greeting' : undefined
 
 if (!arg) {
   // no argument → launch the app
@@ -47,19 +51,25 @@ if (!arg) {
       'Usage:',
       '  clauddy            launch the widget',
       '  clauddy <state>    poke the running widget (just for fun)',
+      '  clauddy say [kind] make the pet say one of its remarks',
       '',
       'States: fire, sleeping, working, tired, idle, poke, celebrate, auto',
+      `Remarks: ${REMARKS.join(', ')}`,
       '(the widget must be running for a state to show)',
     ].join('\n'),
   )
+} else if (kind && !REMARKS.includes(kind)) {
+  console.error(`clauddy: unknown remark "${kind}"`)
+  console.error(`try: ${REMARKS.join(', ')}`)
+  process.exit(1)
 } else if (STATES.includes(arg)) {
   // write the state for the running app to pick up
   fs.mkdirSync(dataDir, { recursive: true })
   fs.writeFileSync(
     path.join(dataDir, 'debug.json'),
-    `${JSON.stringify({ state: arg, t: Date.now() })}\n`,
+    `${JSON.stringify({ state: arg, kind, t: Date.now() })}\n`,
   )
-  console.log(`clauddy → ${arg} (the running widget will react)`)
+  console.log(`clauddy → ${arg}${kind ? ` ${kind}` : ''} (the running widget will react)`)
 } else {
   console.error(`clauddy: unknown command "${arg}"`)
   console.error('try: fire, sleeping, working, tired, idle, poke, celebrate, auto — or --help')

package/main.js

@@ -19,6 +19,7 @@ const { getUsage } = usage
 const auth = require('./auth')
 const accounts = require('./accounts')
 const codex = require('./codex')
+const { createReminders } = require('./reminders')
 
 const REPO = 'renatoaug/claude-usage-monitor'
 const USAGE_URLS = {
@@ -50,6 +51,7 @@ const WINDOW_STATE = path.join(DATA_DIR, 'window.json')
 
 let win
 let pollTimer
+let petPointerTimer
 let config
 let doTick = null
 const W = 304
@@ -61,6 +63,8 @@ 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 codexUsage = null // last Codex payload, null while it isn't enabled
+let realUsageAt = 0
+let codexReadAt = 0
 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
@@ -77,6 +81,9 @@ function publicConfig(c) {
     fireThreshold: c.fireThreshold,
     zoom: c.zoom,
     codex: !!c.codex?.enabled,
+    talk: c.talk,
+    sound: c.sound,
+    soundMutedUntil: c.soundMutedUntil,
   }
 }
 
@@ -92,6 +99,9 @@ function loadConfig() {
     fireThreshold: 90, // session % at which the pet catches fire (tired still fixed at 100)
     zoom: 100, // widget scale %, 100-200
     codex: { enabled: false }, // opt-in from Settings, never on by finding ~/.codex
+    talk: true, // speech bubbles on transitions
+    sound: false, // chiptune blips: opt-in, audio must never surprise anyone
+    soundMutedUntil: 0, // the one-click "mute for 1 hour", as an epoch ms
     pollIntervalMs: 4000,
     activeThresholdMs: 20000,
     sleepThresholdMs: 300000,
@@ -147,6 +157,96 @@ function notify(title, body, { silent = true } = {}) {
   n.show()
 }
 
+// Explicit reminders survive restarts and belong to the account that armed them.
+const REMINDERS_FILE = path.join(DATA_DIR, 'reset-reminders.json')
+const resetReminders = createReminders({
+  now: () => Date.now(),
+  load: () => JSON.parse(fs.readFileSync(REMINDERS_FILE, 'utf8')),
+  save: (data) => {
+    fs.mkdirSync(DATA_DIR, { recursive: true })
+    const tmp = `${REMINDERS_FILE}.tmp`
+    fs.writeFileSync(tmp, JSON.stringify(data))
+    fs.renameSync(tmp, REMINDERS_FILE)
+  },
+})
+const reminderKey = (provider) => (provider === 'codex' ? 'codex' : `claude:${accounts.activeId()}`)
+function sendReminders(error = null) {
+  if (!win || win.isDestroyed()) return
+  win.webContents.send('reminders', {
+    claude: resetReminders.list().find((r) => r.key === reminderKey('claude')) || null,
+    codex: resetReminders.list().find((r) => r.key === 'codex') || null,
+    error,
+  })
+}
+function cancelReminder(key) {
+  try {
+    resetReminders.cancel(key)
+    sendReminders()
+    return true
+  } catch (err) {
+    console.error('reset reminder:', err)
+    sendReminders('Could not cancel the reminder. Please try again.')
+    return false
+  }
+}
+function checkResetReminders() {
+  try {
+    for (const r of resetReminders.list()) {
+      const connected =
+        r.provider === 'codex'
+          ? config.codex?.enabled
+          : accounts.list().some((a) => r.key === `claude:${a.id}` && hasToken(a.id))
+      if (!connected && !cancelReminder(r.key)) return
+    }
+    const due = resetReminders.takeDue()
+    for (const r of due) {
+      const isCurrent = r.provider === 'codex' || r.key === reminderKey('claude')
+      const session = r.provider === 'codex' ? codexUsage?.session : realUsage?.session
+      const readAt = r.provider === 'codex' ? codexUsage?.limitsAt : realUsageAt
+      const confirmed = isCurrent && readAt >= r.at && session?.pct != null && session.pct < r.pct
+      const message = confirmed
+        ? `${r.label}: session budget is available again.`
+        : `${r.label}: the scheduled session reset time has arrived. Open usage to confirm the new budget.`
+      notify(
+        confirmed ? 'Your session budget is back' : 'Time to check your session budget',
+        message,
+      )
+      if (win && !win.isDestroyed())
+        win.webContents.send('reminder-due', { ...r, confirmed, isCurrent })
+    }
+    if (due.length) sendReminders()
+  } catch (err) {
+    console.error('reset reminder:', err)
+  }
+}
+ipcMain.on('set-reminder', (_e, provider, enabled) => {
+  if (!['claude', 'codex'].includes(provider) || typeof enabled !== 'boolean') return
+  const key = reminderKey(provider)
+  if (!enabled) return cancelReminder(key)
+  const cx = provider === 'codex'
+  const session = cx ? codexUsage?.session : realUsage?.session
+  const at = (cx ? codexReadAt : realUsageAt) + (session?.resetMs || 0)
+  const freshAt = cx ? codexUsage?.limitsAt : realUsageAt
+  const connected = cx ? config.codex?.enabled : auth.isConnected()
+  if (
+    !connected ||
+    !freshAt ||
+    Date.now() - freshAt > 15 * 60000 ||
+    !Number.isFinite(session?.pct)
+  ) {
+    return sendReminders('Wait for a fresh usage reading before setting a reminder.')
+  }
+  try {
+    const label = cx ? 'Codex' : `Claude · ${accounts.active().label || 'your account'}`
+    if (!resetReminders.arm({ key, provider, label, at, pct: session.pct })) {
+      return sendReminders('This reset time has passed. Wait for a fresh reading.')
+    }
+    sendReminders()
+  } catch {
+    sendReminders('Could not save the reminder. Please try again.')
+  }
+})
+
 // 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) {
@@ -226,7 +326,14 @@ function checkWindowReset(config, pct) {
   if (pct == null) return
   const was = lastSessionPct
   lastSessionPct = pct
-  if (config.alerts && was != null && was >= RESET_FROM && pct <= RESET_TO) {
+  if (
+    config.alerts &&
+    was != null &&
+    was >= RESET_FROM &&
+    pct <= RESET_TO &&
+    !resetReminders.list().some((r) => r.key === reminderKey('claude')) &&
+    !resetReminders.recentlyDelivered(reminderKey('claude'))
+  ) {
     notify('Session window reset', 'full budget again')
   }
   if (was == null || Math.round(was) !== Math.round(pct)) saveAlertState()
@@ -253,6 +360,7 @@ function applyAccount(acc) {
   lastSessionPct = null
   lastSeenTokens = null // the new account's first read is a baseline, not a spend
   loadAlertState()
+  sendReminders()
 }
 
 // `connected` is read off disk rather than through auth, which only ever knows
@@ -340,7 +448,10 @@ ipcMain.on('accounts-cancel-add', () => {
   switchAccount(from) // the empty slot is pruned on the way out
 })
 ipcMain.on('accounts-remove', (_e, id) => {
-  if (accounts.remove(String(id))) sendAccounts()
+  if (accounts.remove(String(id))) {
+    cancelReminder(`claude:${id}`)
+    sendAccounts()
+  }
 })
 
 function createWindow() {
@@ -379,6 +490,9 @@ function createWindow() {
       preload: path.join(__dirname, 'preload.js'),
       contextIsolation: true,
       nodeIntegration: false,
+      // the pet's blips start from a usage change, never from a click, so
+      // Chromium would otherwise hold the AudioContext suspended
+      autoplayPolicy: 'no-user-gesture-required',
     },
   })
 
@@ -429,12 +543,14 @@ function createWindow() {
     try {
       const c = config.codex?.enabled ? codex.getCodexUsage() : null
       codexUsage = c
+      codexReadAt = Date.now()
       win.webContents.send('codex', c)
       checkCodexAlerts(config, c)
       updateTray()
     } catch (err) {
       console.error('codex:', err)
     }
+    checkResetReminders()
   }
   doTick = tick
 
@@ -442,6 +558,7 @@ function createWindow() {
     tick()
     win.webContents.send('config', publicConfig(config))
     win.webContents.send('version', app.getVersion())
+    sendReminders()
     win.webContents.send('auth-state', { connected: auth.isConnected() })
     sendAccounts()
     pollTimer = setInterval(tick, config.pollIntervalMs)
@@ -650,12 +767,38 @@ function updateTray() {
 // send real usage to the renderer and refresh the tray title in one place
 function pushRealUsage(u) {
   realUsage = u
+  realUsageAt = u ? Date.now() : 0
   sessionPct = u?.session ? u.session.pct : null
   updateTray()
   checkScopedAlerts(config, u)
   if (win && !win.isDestroyed()) win.webContents.send('real-usage', u)
 }
 
+// Native drag regions swallow renderer pointer events. Poll only in pet-only
+// mode so its hover still works while the sprite remains a native drag handle.
+ipcMain.on('pet-pointer-watch', (_e, enabled) => {
+  if (typeof enabled !== 'boolean') return
+  clearInterval(petPointerTimer)
+  petPointerTimer = null
+  if (!enabled) return
+  let last // only a moved cursor crosses IPC, not ten idle messages a second
+  petPointerTimer = setInterval(() => {
+    if (!win || win.isDestroyed()) return
+    let point = null
+    if (win.isVisible()) {
+      const cursor = screen.getCursorScreenPoint()
+      const bounds = win.getContentBounds()
+      const x = cursor.x - bounds.x
+      const y = cursor.y - bounds.y
+      if (x >= 0 && y >= 0 && x < bounds.width && y < bounds.height) point = { x, y }
+    }
+    const key = point ? `${point.x},${point.y}` : ''
+    if (key === last) return
+    last = key
+    win.webContents.send('pet-pointer', point)
+  }, 100)
+})
+
 // resize the window to fit the content
 ipcMain.on('resize', (_e, w, h) => {
   if (!win || win.isDestroyed()) return
@@ -733,9 +876,11 @@ function scheduleUsagePoll() {
   if (auth.isConnected()) usageTimer = setTimeout(pollUsage, usageBackoff)
 }
 async function pollUsage() {
+  const accountId = accounts.activeId()
   lastPollAt = Date.now()
   try {
     const u = await auth.fetchUsage()
+    if (accountId !== accounts.activeId()) return
     usageBackoff = 5 * 60 * 1000
     authFails = 0
     pushRealUsage(u)
@@ -747,6 +892,7 @@ async function pollUsage() {
       sendProfile()
     }
   } catch (e) {
+    if (accountId !== accounts.activeId()) return
     if (e && e.status === 429) {
       usageBackoff = Math.min(usageBackoff * 2, 30 * 60 * 1000)
     } else if (e && e.status === 401) {
@@ -861,6 +1007,7 @@ ipcMain.on('auth-code', async (_e, code) => {
   }
 })
 ipcMain.on('auth-logout', () => {
+  cancelReminder(reminderKey('claude'))
   auth.clear()
   clearTimeout(usageTimer)
   pushRealUsage(null)
@@ -876,7 +1023,10 @@ ipcMain.on('auth-logout', () => {
 function setCodexEnabled(on) {
   writeConfigPatch({ codex: { ...(config.codex || {}), enabled: on } })
   config = loadConfig()
-  if (!on) codexUsage = null
+  if (!on) {
+    codexUsage = null
+    cancelReminder('codex')
+  }
   if (win && !win.isDestroyed()) win.webContents.send('config', publicConfig(config))
   if (doTick) doTick()
   updateTray()
@@ -1020,6 +1170,7 @@ app.whenReady().then(() => {
 
 app.on('window-all-closed', () => {
   if (pollTimer) clearInterval(pollTimer)
+  clearInterval(petPointerTimer)
   fs.unwatchFile(DEBUG_FILE)
   destroyTray()
   app.quit()

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clauddy",
   "desktopName": "clauddy.desktop",
-  "version": "1.24.0",
+  "version": "1.26.0",
   "description": "A cute desktop pet that tracks your Claude Code usage",
   "main": "main.js",
   "bin": {
@@ -15,6 +15,7 @@
     "auth.js",
     "accounts.js",
     "codex.js",
+    "reminders.js",
     "config.json",
     "renderer"
   ],
@@ -75,6 +76,7 @@
       "auth.js",
       "accounts.js",
       "codex.js",
+      "reminders.js",
       "config.json",
       "renderer/**",
       "build/trayTemplate.png",

package/preload.js

@@ -1,6 +1,11 @@
 const { contextBridge, ipcRenderer } = require('electron')
 
 contextBridge.exposeInMainWorld('api', {
+  watchPetPointer: (enabled) => ipcRenderer.send('pet-pointer-watch', enabled),
+  onPetPointer: (cb) => ipcRenderer.on('pet-pointer', (_e, point) => cb(point)),
+  setReminder: (provider, enabled) => ipcRenderer.send('set-reminder', provider, enabled),
+  onReminders: (cb) => ipcRenderer.on('reminders', (_e, state) => cb(state)),
+  onReminderDue: (cb) => ipcRenderer.on('reminder-due', (_e, event) => cb(event)),
   onUsage: (cb) => ipcRenderer.on('usage', (_e, data) => cb(data)),
   onError: (cb) => ipcRenderer.on('usage-error', (_e, msg) => cb(msg)),
   onConfig: (cb) => ipcRenderer.on('config', (_e, cfg) => cb(cfg)),

package/reminders.js

@@ -0,0 +1,53 @@
+// One-shot reset reminders, independent of automatic threshold alerts.
+function createReminders({ load, save, now = Date.now }) {
+  let pending = []
+  let delivered = {}
+  const valid = (r) =>
+    r &&
+    ['claude', 'codex'].includes(r.provider) &&
+    typeof r.key === 'string' &&
+    typeof r.label === 'string' &&
+    Number.isFinite(r.at) &&
+    Number.isFinite(r.pct)
+  try {
+    const data = load()
+    pending = Array.isArray(data?.pending) ? data.pending.filter(valid) : []
+    delivered = data?.delivered || {}
+  } catch {}
+  function persist(nextPending, nextDelivered = delivered) {
+    const recent = Object.fromEntries(
+      Object.entries(nextDelivered).filter(([, at]) => Number.isFinite(at) && now() - at < 3600000),
+    )
+    save({ pending: nextPending, delivered: recent })
+    pending = nextPending
+    delivered = recent
+  }
+  return {
+    list: () => pending.map((r) => ({ ...r })),
+    arm(reminder) {
+      if (!valid(reminder) || reminder.at <= now() || reminder.at > now() + 7 * 86400000)
+        return false
+      persist([...pending.filter((r) => r.key !== reminder.key), { ...reminder }])
+      return true
+    },
+    cancel(key) {
+      const found = pending.some((r) => r.key === key)
+      if (found) persist(pending.filter((r) => r.key !== key))
+    },
+    takeDue() {
+      const due = pending.filter((r) => r.at <= now())
+      if (!due.length) return []
+      const nextDelivered = { ...delivered }
+      for (const r of due) nextDelivered[r.key] = now()
+      // Consume before delivering: restart must not replay it.
+      persist(
+        pending.filter((r) => r.at > now()),
+        nextDelivered,
+      )
+      return due
+    },
+    recentlyDelivered: (key) => Number.isFinite(delivered[key]) && now() - delivered[key] < 3600000,
+  }
+}
+
+module.exports = { createReminders }

package/renderer/companion.js

@@ -0,0 +1,48 @@
+// A quiet transition detector. Startup and reconnects establish a baseline;
+// inactivity is a pause, never proof that an agent finished its task.
+;((root) => {
+  function createActivityTracker({ now = Date.now, cooldown = 30000 } = {}) {
+    const seen = new Map()
+    let lastCue = -Infinity
+    return {
+      forget(provider) {
+        seen.delete(provider)
+      },
+      observe(provider, data) {
+        if (!data) {
+          seen.delete(provider)
+          return null
+        }
+        const next = { active: !!data.active, activity: data.activity || 'working' }
+        const previous = seen.get(provider)
+        seen.set(provider, next)
+        if (!previous) return null
+        const changed =
+          next.active !== previous.active || (next.active && next.activity !== previous.activity)
+        if (!changed || now() - lastCue < cooldown) return null
+        lastCue = now()
+        return { provider, activity: next.active ? next.activity : 'paused' }
+      },
+    }
+  }
+  // Activity freshness is separate from quota freshness: Codex can work while
+  // its last rate-limit reading is old. Ignore abandoned activity snapshots.
+  const FRESH_MS = 60000
+  const SLEEP_MS = 300000 // main's default sleepThresholdMs; Codex has no flag of its own
+  function currentActivity(claude, codex, now = Date.now()) {
+    const fresh = (at) => Number.isFinite(at) && now - at <= FRESH_MS
+    const providers = []
+    if (claude?.active && fresh(claude.ts)) providers.push('claude')
+    if (codex?.active && fresh(codex.lastSeen)) providers.push('codex')
+    // only Claude's logs say *what* it's doing; two workers share one scene
+    const activity = providers.join() === 'claude' ? claude.activity || 'working' : 'working'
+    const asleep = [
+      claude && !!claude.sleeping,
+      codex && !!codex.lastSeen && now - codex.lastSeen >= SLEEP_MS,
+    ].filter((v) => v !== null && v !== undefined)
+    return { providers, activity, sleeping: asleep.length > 0 && asleep.every(Boolean) }
+  }
+  const api = { createActivityTracker, currentActivity }
+  if (typeof module === 'object' && module.exports) module.exports = api
+  else root.Companion = api
+})(globalThis)