unsnooze 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 1.4.0 — 2026-07-12
+
+- **Update notices**: unsnooze now checks the npm registry (at most once a
+  day, a plain GET with nothing identifying) and tells you when a new version
+  is out — a one-line notice after CLI commands, and a single desktop toast
+  per version from the daemon. After you update, the next command shows a
+  short "what's new" straight from the bundled changelog. Turn it all off
+  with `unsnooze config set updateCheck off`.
+
+## 1.3.0 — 2026-07-11
+
+- **Per-session wake messages**: `unsnooze message <id|--all> "<text>"` sets a
+  custom resume message for specific tracked sessions (`--clear` reverts).
+  Precedence: per-session → per-agent (`resumeMessages.<id>`) → global
+  `resumeMessage`. Applies on both wake paths — typed into a live pane, or
+  carried in argv for `codex resume` — and sessions with a custom message
+  show a `msg: "…"` marker in `unsnooze status`.
+
 ## 1.2.0 — 2026-07-10
 
 ### GUI surfaces: VS Code extension, desktop apps

package/README.md

@@ -9,9 +9,10 @@
 [![node](https://img.shields.io/badge/node-%E2%89%A5%2020-3fb950)](package.json)
 [![license](https://img.shields.io/badge/license-MIT-8b949e)](LICENSE)
 
-**Claude Code · Codex CLI · Grok** — when they hit a usage limit, your session just… stops.<br/>
-unsnooze tracks **every** limit-stopped session across all your projects and
-**wakes each one up in tmux the moment the limit resets.**
+**Claude Code · Codex CLI · Grok** — when they hit the 5-hour or weekly usage limit
+("You've hit your usage limit"), your session just… stops.<br/>
+unsnooze auto-resumes them: it tracks **every** limit-stopped session across all
+your projects and **wakes each one up in tmux the moment the usage limit resets.**
 
 ```sh
 npm install -g unsnooze && unsnooze setup
@@ -128,6 +129,7 @@ claude / codex / grok           # normal usage — wrapped automatically
 unsnooze status                 # tracked sessions + reset countdowns
 unsnooze resume-now [id|--all]  # don't wait for the reset time
 unsnooze cancel [id|--all]      # stop tracking a session
+unsnooze message <id> "text"    # per-session wake message (--clear to reset)
 unsnooze config list            # settings (see below)
 unsnooze config set <k> <v>     # e.g. autoResume off
 unsnooze logs [-f]              # what unsnooze has been doing
@@ -149,9 +151,10 @@ unsnooze help                   # full command list (also -h / --help)
 | `menuAutoAnswer` | `true` | May unsnooze answer Claude's limit menu (send keys in your pane)? Off = watch-only. |
 | `notifications` | `true` | Desktop notification on limit detected / session resumed / gave up. |
 | `guiWatch` | `true` | May the daemon watch session files for GUI-surface stops (VS Code extension, desktop apps)? Needs the daemon running (`unsnooze install --daemon`). |
-| `resumeMessage` | *"Continue where you left off…"* | The message sent to wake a session. |
+| `resumeMessage` | *"Continue where you left off…"* | The message sent to wake a session. Override it for a single session with `unsnooze message <id> "…"` — visible in `unsnooze status`. |
 | `resumeMessages.claude` / `.codex` / `.grok` | `""` | Per-agent override of `resumeMessage`. Empty = use the global message; clear one with `unsnooze config set resumeMessages.claude ""`. |
 | `agents.claude` / `agents.codex` / `agents.grok` | `true` / `true` / `false` | Which CLIs are guarded. |
+| `updateCheck` | `true` | Daily new-version check (a plain GET to the npm registry, nothing identifying is sent). Notices after commands + one desktop toast per version. |
 
 Every setting also has a `UNSNOOZE_*` env override (see `src/settings.js`), and
 all timings/paths are tunable via `UNSNOOZE_*` env vars (see `src/config.js`).
@@ -199,6 +202,42 @@ unsnooze raises **native Windows toasts** through `powershell.exe` (no
 not supported — without tmux there is nothing to watch; unsnooze will tell you
 so and run your CLI unwatched instead of breaking it.
 
+## FAQ
+
+### What does "You've hit your usage limit" mean in Claude Code?
+
+Claude subscription plans meter usage in a rolling 5-hour window plus a weekly
+cap. When either runs out, Claude Code stops mid-task and shows the banner with
+a reset time ("resets 3pm"). Nothing is lost — the session can be resumed with
+`claude --resume <id>` once the limit resets. unsnooze does exactly that,
+automatically, for every stopped session.
+
+### What about Codex — "You've hit your usage limit. Try again at …"?
+
+Same idea: ChatGPT-plan Codex has 5-hour and weekly windows. The Codex TUI
+stays open at the composer after the banner, so unsnooze either types into the
+live pane or reopens the session with `codex resume <id>` at the reset time it
+parsed from the banner.
+
+### Does this get around the rate limit?
+
+No. unsnooze waits for the reset exactly like you would, resumes once, and
+verifies the limit actually lifted. It replaces the 4am alarm, not the limit.
+
+### How do I update, and how do I know when to?
+
+`npm i -g unsnooze`. unsnooze checks the npm registry at most once a day and
+tells you when a newer version exists (a line after CLI commands, plus one
+desktop notification per version); after updating, the next command shows a
+short "what's new" from the changelog. It's a plain registry GET with nothing
+identifying — turn it off with `unsnooze config set updateCheck off`.
+
+### Does it work if my laptop was asleep or the terminal was closed?
+
+Yes — reset times are stored as absolute timestamps and checked every 30
+seconds, so a laptop that slept through the reset resumes on the next tick,
+and dead panes are reopened by session id in a fresh tmux window.
+
 ## Development
 
 ```sh

package/bin/unsnooze.js

@@ -4,6 +4,24 @@
 
 const [, , cmd, ...rest] = process.argv;
 
+// Only human-facing commands may print update notices — never the wrapper
+// passthrough, hooks, or daemons (their output lands in agent panes/logs).
+const USER_FACING = new Set(['status', 'resume-now', 'cancel', 'message', 'config', 'logs', 'report', 'help', '-h', '--help', '--help-unsnooze']);
+
+async function maybeUpdateNotices() {
+  try {
+    const { whatsNewNotice, updateNotice, isCacheStale } = await import('../src/update-check.js');
+    const whatsNew = whatsNewNotice();
+    if (whatsNew) console.error(`\n${whatsNew}`);
+    const notice = updateNotice();
+    if (notice) console.error(`\n${notice}`);
+    if (isCacheStale()) {
+      const { spawnDetached } = await import('../src/spawn.js');
+      spawnDetached(['_update-check']);
+    }
+  } catch { /* update UX must never break a command */ }
+}
+
 async function main() {
   switch (cmd) {
     case 'status': {
@@ -30,6 +48,10 @@ async function main() {
       const { cmdReport } = await import('../src/report.js');
       return cmdReport(rest);
     }
+    case 'message': {
+      const { cmdMessage } = await import('../src/cli.js');
+      return cmdMessage(rest);
+    }
     case 'config': {
       const { cmdConfig } = await import('../src/cli.js');
       return cmdConfig(rest);
@@ -60,6 +82,10 @@ async function main() {
       const { runResumer } = await import('../src/resumer.js');
       return runResumer();
     }
+    case '_update-check': {
+      const { runUpdateCheck } = await import('../src/update-check.js');
+      return runUpdateCheck();
+    }
     case 'daemon': {
       // Persistent resumer + transcript watcher: detects and revives limit
       // stops from GUI surfaces (VS Code extension, desktop apps) where no
@@ -69,6 +95,11 @@ async function main() {
       const controller = new AbortController();
       process.on('SIGTERM', () => controller.abort());
       process.on('SIGINT', () => controller.abort());
+      // Daily update check from the daemon: GUI-only users never run CLI
+      // commands, so this is what gets them the "new version" desktop toast.
+      const { spawnDetached } = await import('../src/spawn.js');
+      spawnDetached(['_update-check']);
+      setInterval(() => spawnDetached(['_update-check']), 24 * 3_600_000).unref();
       return runResumer({ persistent: true, watcher: createWatcher(), signal: controller.signal });
     }
     case 'help':
@@ -83,12 +114,13 @@ Usage:
   unsnooze status                  list tracked sessions + reset countdowns
   unsnooze resume-now [id|--all]   resume stopped session(s) immediately
   unsnooze cancel [id|--all]       stop tracking session(s)
+  unsnooze message <id|--all> <t>  set a per-session wake message (--clear to reset)
   unsnooze logs [-f]               show (or follow) the unsnooze log
   unsnooze daemon                  persistent watcher for GUI sessions (VS Code
                                    extension, desktop apps) — no tmux needed to
                                    detect; revival still opens in tmux
   unsnooze config [list|get|set]   view or change settings (toggles, global +
-                                   per-agent resume messages)
+                                   per-agent resume messages, updateCheck)
   unsnooze setup                   interactive setup wizard (agents + toggles)
   unsnooze install [--yes]         wire up shell wrappers + hooks (non-interactive)
   unsnooze uninstall [--purge]     remove wrappers + hooks (and state with --purge)
@@ -106,5 +138,7 @@ Usage:
   }
 }
 
-main().then(code => { process.exitCode = typeof code === 'number' ? code : 0; })
-  .catch(err => { console.error(`unsnooze: ${err.stack || err}`); process.exitCode = 1; });
+main().then(async code => {
+  if (USER_FACING.has(cmd)) await maybeUpdateNotices();
+  process.exitCode = typeof code === 'number' ? code : 0;
+}).catch(err => { console.error(`unsnooze: ${err.stack || err}`); process.exitCode = 1; });

package/package.json

@@ -1,17 +1,27 @@
 {
   "name": "unsnooze",
-  "version": "1.2.0",
-  "description": "Wakes every limit-stopped AI coding session (Claude Code, Codex CLI, Grok) in tmux the moment the usage limit resets.",
+  "version": "1.4.0",
+  "description": "Auto-resume Claude Code, Codex CLI & Grok sessions in tmux when the usage limit (5-hour or weekly) resets. Wakes every limit-stopped AI coding session automatically.",
   "keywords": [
+    "claude",
     "claude-code",
     "codex",
     "codex-cli",
+    "openai",
+    "anthropic",
     "grok",
     "usage-limit",
+    "usage limit",
     "rate-limit",
+    "rate limit",
+    "5-hour limit",
     "auto-resume",
+    "auto-retry",
+    "resume",
+    "retry",
     "tmux",
     "ai-agents",
+    "agentic-coding",
     "cli"
   ],
   "author": "Saaransh Menon <saaransh.dev2811@gmail.com>",

package/src/cli.js

@@ -30,16 +30,19 @@ export function cmdStatus() {
     const id = s.sessionId ? s.sessionId.slice(0, 8) : '(no id)';
     const reset = s.resetAt ? `${new Date(s.resetAt).toLocaleString()} (${fmtCountdown(s.resetAt - now)})` : '?';
     const origin = s.origin ?? (s.pane ? 'cli' : '?');
+    const msg = s.resumeMessage
+      ? ` · msg: "${s.resumeMessage.length > 44 ? s.resumeMessage.slice(0, 44) + '…' : s.resumeMessage}"`
+      : '';
     console.log(`  [${s.status.toUpperCase().padEnd(9)}] ${id}  ${(s.agent || 'claude').padEnd(6)} ${s.limitType?.padEnd(7) ?? 'unknown'} ${s.cwd}`);
-    console.log(`              pane ${s.pane ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}`);
+    console.log(`              pane ${s.pane ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}`);
   }
   return 0;
 }
 
-function selectKeys(state, idOrAll) {
-  const stopped = Object.values(state.sessions).filter(s => s.status === 'stopped');
-  if (idOrAll === '--all' || idOrAll === undefined) return stopped.map(s => s.key);
-  const match = stopped.filter(s => s.key.startsWith(idOrAll) || (s.sessionId || '').startsWith(idOrAll));
+function selectKeys(state, idOrAll, statuses = ['stopped']) {
+  const candidates = Object.values(state.sessions).filter(s => statuses.includes(s.status));
+  if (idOrAll === '--all' || idOrAll === undefined) return candidates.map(s => s.key);
+  const match = candidates.filter(s => s.key.startsWith(idOrAll) || (s.sessionId || '').startsWith(idOrAll));
   return match.map(s => s.key);
 }
 
@@ -82,6 +85,33 @@ export function cmdLogs(follow) {
   return 0;
 }
 
+// `unsnooze message <id|--all> <text...>` — set (or --clear) the wake message
+// for specific sessions; the resumer prefers it over the global setting.
+export function cmdMessage(rest) {
+  const [idOrAll, ...textParts] = rest;
+  const clear = textParts[0] === '--clear';
+  const text = textParts.join(' ').trim();
+  if (!idOrAll || (!clear && !text)) {
+    console.error('unsnooze message <id|--all> <text...>   (or --clear to revert to the default)');
+    return 2;
+  }
+  const state = readState();
+  // stopped OR resuming: editing the message before a retry is legitimate.
+  const keys = selectKeys(state, idOrAll, ['stopped', 'resuming']);
+  if (keys.length === 0) { console.log('unsnooze: no matching active sessions.'); return 1; }
+  updateState(s => {
+    for (const key of keys) {
+      if (!s.sessions[key]) continue;
+      if (clear) delete s.sessions[key].resumeMessage;
+      else s.sessions[key].resumeMessage = text;
+    }
+  });
+  console.log(clear
+    ? `unsnooze: cleared custom message on ${keys.length} session(s) (global default applies).`
+    : `unsnooze: ${keys.length} session(s) will wake with: "${text}"`);
+  return 0;
+}
+
 // `unsnooze config list | get <key> | set <key> <value>`
 export function cmdConfig(rest) {
   const [action, key, ...valueParts] = rest;

package/src/resumer.js

@@ -72,8 +72,10 @@ function selfCommand() {
 export async function dispatchOne(rec, { tmux = realTmux, resumeMessage, selfCmd = selfCommand() } = {}) {
   const key = rec.key;
   const agent = getAgent(rec.agent);
-  // Explicit option wins; otherwise the agent's own message (or the global).
-  resumeMessage = resumeMessage ?? resolveResumeMessage(agent.id);
+  // Wake-message precedence: per-session (`unsnooze message <id> "..."`) →
+  // explicit option → per-agent (`resumeMessages.<id>`) → global. Applies to
+  // both the live-pane sendText and the argv reopen path.
+  resumeMessage = rec.resumeMessage ?? resumeMessage ?? resolveResumeMessage(agent.id);
 
   // Live-pane path: only if the pane still exists AND the agent CLI is its
   // foreground command (pane ids get recycled — never inject into a random

package/src/settings.js

@@ -17,6 +17,7 @@ export const DEFAULTS = {
   menuAutoAnswer: true,    // may unsnooze drive Claude's limit menu (send keys)?
   notifications: true,     // desktop notifications on detect/resume
   guiWatch: true,          // daemon watches transcripts/rollouts for GUI-session stops
+  updateCheck: true,       // daily registry version check + update notices/toast
   resumeMessage: 'Continue where you left off. The session was interrupted by a usage limit which has now reset — pick up the task you were working on and finish it.',
   resumeMessages: { claude: '', codex: '', grok: '' },  // per-agent override; '' = use resumeMessage
   agents: { claude: true, codex: true, grok: false },   // grok is experimental
@@ -28,6 +29,7 @@ const ENV_NAMES = {
   menuAutoAnswer: 'UNSNOOZE_MENU_AUTO_ANSWER',
   notifications: 'UNSNOOZE_NOTIFICATIONS',
   guiWatch: 'UNSNOOZE_GUI_WATCH',
+  updateCheck: 'UNSNOOZE_UPDATE_CHECK',
   resumeMessage: 'UNSNOOZE_RESUME_MESSAGE',
   'resumeMessages.claude': 'UNSNOOZE_RESUME_MESSAGE_CLAUDE',
   'resumeMessages.codex': 'UNSNOOZE_RESUME_MESSAGE_CODEX',

package/src/state.js

@@ -96,6 +96,9 @@ export function upsertSession(record) {
         ...record,
         // Never downgrade a known sessionId to null.
         sessionId: record.sessionId || existing.sessionId,
+        // A detection that races an in-flight resume must not flip the record
+        // back to 'stopped' — the post-resume verify pass owns that outcome.
+        status: existing.status === 'resuming' ? existing.status : record.status,
         key: existingKey,
       };
       state.sessions[existingKey] = merged;
@@ -114,8 +117,11 @@ function findDuplicate(state, record) {
     // Same sessionId living under a pane-based key (a scrape record that later
     // learned its id through a merge).
     if (record.sessionId && s.sessionId === record.sessionId) return key;
+    // 'resuming' counts too: while the resumer types into a pane, a scrape can
+    // still see the banner for a few hundred ms — that must not fork a second
+    // record (it would double-resume the session).
     if (s.pane && s.pane === record.pane
-      && s.status === 'stopped'
+      && (s.status === 'stopped' || s.status === 'resuming')
       && Math.abs((s.detectedAt || 0) - record.detectedAt) < DEDUPE_WINDOW_MS) {
       return key;
     }

package/src/update-check.js

@@ -0,0 +1,120 @@
+// Update notifications. npm can't push updates, so the CLI nudges:
+//   - user-facing commands print a one-line notice (from CACHE only — the
+//     registry fetch happens in a detached `_update-check`, never inline)
+//   - the daemon fires ONE desktop toast per new version
+//   - after the user updates, the next command shows "what's new" straight
+//     from the CHANGELOG.md bundled in the npm tarball (zero network)
+// All of it is gated on the `updateCheck` setting / UNSNOOZE_UPDATE_CHECK.
+// The check is a plain GET to registry.npmjs.org — nothing identifying.
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getConfig } from './settings.js';
+import { notify } from './notify.js';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+export const PKG_VERSION = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8')).version;
+
+const CACHE_FILE = () => join(process.env.UNSNOOZE_STATE_DIR || join(process.env.HOME || '', '.unsnooze'), 'update-check.json');
+const CHECK_INTERVAL_MS = 24 * 3_600_000;
+const RELEASES_URL = 'https://github.com/saaranshM/unsnooze/releases';
+
+export function readCache() {
+  try { return JSON.parse(readFileSync(CACHE_FILE(), 'utf-8')); } catch { return {}; }
+}
+
+export function writeCache(patch) {
+  const merged = { ...readCache(), ...patch };
+  const path = CACHE_FILE();
+  mkdirSync(dirname(path), { recursive: true });
+  const tmp = join(dirname(path), `.update-check.tmp.${process.pid}`);
+  writeFileSync(tmp, JSON.stringify(merged, null, 2) + '\n');
+  renameSync(tmp, path);
+  return merged;
+}
+
+// Plain x.y.z compare. We never publish prereleases; anything that isn't
+// three numbers loses (a garbage registry response must never nag).
+export function isNewer(candidate, current) {
+  const parse = v => (typeof v === 'string' && /^\d+\.\d+\.\d+$/.test(v)) ? v.split('.').map(Number) : null;
+  const a = parse(candidate);
+  const b = parse(current);
+  if (!a || !b) return false;
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] > b[i];
+  }
+  return false;
+}
+
+export function isCacheStale(now = Date.now()) {
+  return now - (readCache().lastCheckedAt || 0) > CHECK_INTERVAL_MS;
+}
+
+export async function fetchLatest({ fetcher = globalThis.fetch, timeoutMs = 3000 } = {}) {
+  try {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+      const res = await fetcher('https://registry.npmjs.org/unsnooze/latest', {
+        signal: ctrl.signal, headers: { accept: 'application/json' },
+      });
+      if (!res.ok) return null;
+      const body = await res.json();
+      return typeof body?.version === 'string' ? body.version : null;
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch {
+    return null;   // offline, timeout, bad JSON — never the CLI's problem
+  }
+}
+
+// Cache-only, instant. Printed to stderr after user-facing commands.
+export function updateNotice(pkgVersion = PKG_VERSION) {
+  if (!getConfig('updateCheck')) return null;
+  const { latest } = readCache();
+  if (!latest || !isNewer(latest, pkgVersion)) return null;
+  return `unsnooze ${latest} is available (you have ${pkgVersion}) — npm i -g unsnooze · ${RELEASES_URL}`;
+}
+
+// The "## <version>" block from the CHANGELOG.md that ships in the tarball.
+export function changelogSection(version, maxLines = 6) {
+  try {
+    const lines = readFileSync(join(ROOT, 'CHANGELOG.md'), 'utf-8').split('\n');
+    const start = lines.findIndex(l => l.startsWith(`## ${version}`));
+    if (start === -1) return null;
+    const rest = lines.slice(start + 1);
+    const end = rest.findIndex(l => l.startsWith('## '));
+    const section = rest.slice(0, end === -1 ? undefined : end)
+      .filter(l => l.trim() !== '')
+      .slice(0, maxLines);
+    return section.length ? section.join('\n') : null;
+  } catch {
+    return null;
+  }
+}
+
+// Once after an update: "you're now on X, here's what changed."
+export function whatsNewNotice(pkgVersion = PKG_VERSION) {
+  if (!getConfig('updateCheck')) return null;
+  const { lastRunVersion } = readCache();
+  if (lastRunVersion === pkgVersion) return null;
+  writeCache({ lastRunVersion: pkgVersion });
+  if (!lastRunVersion) return null;   // first ever run — nothing to announce
+  const section = changelogSection(pkgVersion);
+  return `Updated to ${pkgVersion}.` + (section ? ` What's new:\n${section}` : ` ${RELEASES_URL}/tag/v${pkgVersion}`);
+}
+
+// The detached `_update-check`: fetch, cache, toast once per new version.
+export async function runUpdateCheck({ fetcher, notifier = notify, now = Date.now() } = {}) {
+  if (!getConfig('updateCheck')) return 0;
+  const latest = await fetchLatest({ fetcher });
+  if (!latest) return 0;
+  const cache = writeCache({ lastCheckedAt: now, latest });
+  if (isNewer(latest, PKG_VERSION) && cache.notifiedVersion !== latest) {
+    notifier('unsnooze update available', `${latest} is out (you have ${PKG_VERSION}) — npm i -g unsnooze`);
+    writeCache({ notifiedVersion: latest });
+  }
+  return 0;
+}