unsnooze 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.1.0 — 2026-07-10
+
+### Per-agent resume messages
+
+- **`resumeMessages.claude` / `.codex` / `.grok`**: optional per-agent override
+  of the global `resumeMessage` — `unsnooze config set resumeMessages.codex
+  "..."` or `UNSNOOZE_RESUME_MESSAGE_CODEX`. Empty means "use the global
+  message"; clear with `unsnooze config set resumeMessages.codex ""`.
+  Specificity beats source: a per-agent file value outranks a global env var.
+- **Setup wizard** asks for per-agent messages, prefills every message prompt
+  from the existing config, and merges over the config file — re-runs no
+  longer clobber values set via `unsnooze config`.
+- Blank or whitespace-only messages are never sent: resolution falls through
+  to the global message, then the built-in default.
+
+### CLI & fixes
+
+- **`-h` / `--help`** now print the unsnooze help (previously only
+  `unsnooze help`), and the usage documents every command.
+- **Install**: `unsnooze setup` / `install` no longer crashes with ENOENT on
+  machines without a `~/.claude/` directory.
+- `unsnooze config set <key> ""` is a valid way to clear string overrides, and
+  a config file holding non-object JSON is treated as empty instead of
+  corrupting later writes.
+
 ## 1.0.0 — 2026-07-10
 
 First public release (previously the private `claude-session-guard`/`csg`).

package/README.md

@@ -103,6 +103,7 @@ unsnooze config set <k> <v>     # e.g. autoResume off
 unsnooze logs [-f]              # what unsnooze has been doing
 unsnooze report [agent]         # capture a pane to report an undetected banner
 unsnooze uninstall [--purge]    # remove wrappers + hooks (+ state with --purge)
+unsnooze help                   # full command list (also -h / --help)
 ```
 
 ## Settings
@@ -116,6 +117,7 @@ unsnooze uninstall [--purge]    # remove wrappers + hooks (+ state with --purge)
 | `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. |
 | `resumeMessage` | *"Continue where you left off…"* | The message sent to wake a session. |
+| `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. |
 
 Every setting also has a `UNSNOOZE_*` env override (see `src/settings.js`), and

package/bin/unsnooze.js

@@ -61,6 +61,8 @@ async function main() {
       return runResumer();
     }
     case 'help':
+    case '-h':
+    case '--help':
     case '--help-unsnooze': {
       console.log(`unsnooze — wakes every limit-stopped AI coding session when the limit resets
 
@@ -71,11 +73,13 @@ Usage:
   unsnooze resume-now [id|--all]   resume stopped session(s) immediately
   unsnooze cancel [id|--all]       stop tracking session(s)
   unsnooze logs [-f]               show (or follow) the unsnooze log
-  unsnooze config [list|get|set]   view or change settings (toggles, message)
+  unsnooze config [list|get|set]   view or change settings (toggles, global +
+                                   per-agent resume messages)
   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)
-  unsnooze report [agent] [pane]   capture a pane to report an undetected banner`);
+  unsnooze report [agent] [pane]   capture a pane to report an undetected banner
+  unsnooze help                    show this help (also -h / --help)`);
       return 0;
     }
     default: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Wakes every limit-stopped AI coding session (Claude Code, Codex CLI, Grok) in tmux the moment the usage limit resets.",
   "keywords": [
     "claude-code",

package/src/cli.js

@@ -89,7 +89,7 @@ export function cmdConfig(rest) {
       const listed = listConfig();
       console.log(`unsnooze settings (${CONFIG_FILE()}):\n`);
       for (const [k, v] of Object.entries(listed)) {
-        console.log(`  ${k.padEnd(16)} ${JSON.stringify(v)}`);
+        console.log(`  ${k.padEnd(24)} ${JSON.stringify(v)}`);
       }
       return 0;
     }
@@ -100,7 +100,9 @@ export function cmdConfig(rest) {
     }
     if (action === 'set') {
       const value = valueParts.join(' ');
-      if (!key || value === '') { console.error('unsnooze config set <key> <value>'); return 2; }
+      // An explicit "" is a valid value (clears string overrides); only a
+      // genuinely missing value is a usage error.
+      if (!key || valueParts.length === 0) { console.error('unsnooze config set <key> <value>'); return 2; }
       const applied = setConfigValue(key, value);
       console.log(`unsnooze: ${key} = ${JSON.stringify(applied)}`);
       return 0;

package/src/install.js

@@ -8,7 +8,7 @@
 //   - ~/.grok/hooks/unsnooze.json when the grok agent is enabled
 // --settings <path> / --zshrc <path> override targets (used by tests).
 
-import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync, rmSync } from 'node:fs';
+import { readFileSync, writeFileSync, renameSync, existsSync, copyFileSync, rmSync, mkdirSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { CLAUDE_SETTINGS, STATE_DIR } from './config.js';
@@ -38,6 +38,7 @@ function parseArgs(rest) {
 }
 
 function atomicWrite(path, content) {
+  mkdirSync(dirname(path), { recursive: true });   // e.g. ~/.claude may not exist yet
   const tmp = join(dirname(path), `.${Date.now()}.tmp`);
   writeFileSync(tmp, content);
   renameSync(tmp, path);

package/src/resumer.js

@@ -16,7 +16,7 @@ import { detectLimit, isBusy } from './patterns.js';
 import { getAgent } from './agents/index.js';
 import { parseResetTime, resetAtMs } from './time-parser.js';
 import { readState, updateState, setStatus, dueSessions, activeStopped } from './state.js';
-import { getConfig } from './settings.js';
+import { getConfig, resolveResumeMessage } from './settings.js';
 import { notify } from './notify.js';
 import { UNSNOOZE_BIN } from './spawn.js';
 import { makeLogger } from './logger.js';
@@ -68,9 +68,11 @@ function selfCommand() {
 
 // Decide how to act on one due record. Pure-ish; tmux injectable.
 // Returns: 'sent' | 'reopened' | 'deferred' | 'skip' | 'failed'
-export async function dispatchOne(rec, { tmux = realTmux, resumeMessage = getConfig('resumeMessage'), selfCmd = 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);
 
   // 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

@@ -1,6 +1,10 @@
 // User-facing settings: ~/.unsnooze/config.json, managed by `unsnooze config`
-// and the setup wizard. Precedence: env var > config file > default — env
-// stays the power-user/test escape hatch, the file is what the wizard writes.
+// and the setup wizard. Precedence per key: env var > config file > default —
+// env stays the power-user/test escape hatch, the file is what the wizard
+// writes. One cross-key exception: the resume message resolves by specificity
+// first, so a per-agent resumeMessages.<id> value (from either source) beats
+// the global resumeMessage even when the global came from an env var (see
+// resolveResumeMessage).
 
 import { readFileSync, writeFileSync, renameSync, mkdirSync } from 'node:fs';
 import { join, dirname } from 'node:path';
@@ -13,6 +17,7 @@ export const DEFAULTS = {
   menuAutoAnswer: true,    // may unsnooze drive Claude's limit menu (send keys)?
   notifications: true,     // desktop notifications on detect/resume
   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
 };
 
@@ -22,6 +27,9 @@ const ENV_NAMES = {
   menuAutoAnswer: 'UNSNOOZE_MENU_AUTO_ANSWER',
   notifications: 'UNSNOOZE_NOTIFICATIONS',
   resumeMessage: 'UNSNOOZE_RESUME_MESSAGE',
+  'resumeMessages.claude': 'UNSNOOZE_RESUME_MESSAGE_CLAUDE',
+  'resumeMessages.codex': 'UNSNOOZE_RESUME_MESSAGE_CODEX',
+  'resumeMessages.grok': 'UNSNOOZE_RESUME_MESSAGE_GROK',
   'agents.claude': 'UNSNOOZE_AGENT_CLAUDE',
   'agents.codex': 'UNSNOOZE_AGENT_CODEX',
   'agents.grok': 'UNSNOOZE_AGENT_GROK',
@@ -35,9 +43,11 @@ function parseBool(raw) {
   return null;
 }
 
-function readFileConfig() {
+export function readFileConfig() {
   try {
-    return JSON.parse(readFileSync(CONFIG_FILE(), 'utf-8'));
+    const parsed = JSON.parse(readFileSync(CONFIG_FILE(), 'utf-8'));
+    // Wrong-typed but valid JSON (a bare string/array) counts as corrupt too.
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
   } catch {
     return {};   // missing or corrupt file → defaults (never crash the hook path)
   }
@@ -63,6 +73,17 @@ export function getConfig(key) {
   return fromFile !== undefined ? fromFile : def;
 }
 
+// The message to send a given agent: its resumeMessages.<id> override when
+// set, else the global resumeMessage. Unknown agent ids fall back to global;
+// blank values (empty or whitespace-only) fall through to the next level so a
+// blank message is never sent.
+export function resolveResumeMessage(agentId) {
+  const key = `resumeMessages.${agentId}`;
+  const set = v => (typeof v === 'string' && v.trim() ? v : '');
+  const perAgent = agentId && KNOWN_KEYS.includes(key) ? getConfig(key) : '';
+  return set(perAgent) || set(getConfig('resumeMessage')) || DEFAULTS.resumeMessage;
+}
+
 export function setConfigValue(key, rawValue) {
   if (!KNOWN_KEYS.includes(key)) throw new Error(`unsnooze: unknown setting "${key}" (known: ${KNOWN_KEYS.join(', ')})`);
   const def = dig(DEFAULTS, key);

package/src/wizard.js

@@ -6,7 +6,7 @@ import { execFileSync } from 'node:child_process';
 import * as p from '@clack/prompts';
 import { listAgents } from './agents/index.js';
 import { isCommunityGrokCli } from './agents/grok.js';
-import { DEFAULTS, writeConfig } from './settings.js';
+import { DEFAULTS, writeConfig, readFileConfig } from './settings.js';
 
 export function detectInstalledAgents({ which = defaultWhich } = {}) {
   return listAgents().map(agent => ({ agent, installed: which(agent.bin) }));
@@ -69,25 +69,55 @@ export async function runWizard() {
   });
   if (p.isCancel(notifications)) return cancelled();
 
+  // Seed message prompts from the existing config so a setup re-run shows —
+  // and keeps — values previously set here or via `unsnooze config`.
+  const existing = readFileConfig();
+  const existingMsgs = existing.resumeMessages
+    && typeof existing.resumeMessages === 'object' && !Array.isArray(existing.resumeMessages)
+    ? existing.resumeMessages : {};
+
   const customizeMsg = await p.confirm({
     message: 'Customize the message sent to resume a session?',
     initialValue: false,
   });
   if (p.isCancel(customizeMsg)) return cancelled();
 
-  let resumeMessage = DEFAULTS.resumeMessage;
+  let resumeMessage = typeof existing.resumeMessage === 'string' && existing.resumeMessage.trim()
+    ? existing.resumeMessage : DEFAULTS.resumeMessage;
   if (customizeMsg) {
     const msg = await p.text({
       message: 'Resume message:',
-      initialValue: DEFAULTS.resumeMessage,
+      initialValue: resumeMessage,
       validate: v => (v.trim() ? undefined : 'message cannot be empty'),
     });
     if (p.isCancel(msg)) return cancelled();
     resumeMessage = msg;
   }
 
+  const customizePerAgent = await p.confirm({
+    message: 'Set a different resume message for specific agents?',
+    initialValue: false,
+  });
+  if (p.isCancel(customizePerAgent)) return cancelled();
+
+  const resumeMessages = {};
+  if (customizePerAgent) {
+    for (const agent of listAgents().filter(a => agents.includes(a.id))) {
+      const msg = await p.text({
+        message: `Message for ${agent.name} (leave empty to use the global message):`,
+        initialValue: typeof existingMsgs[agent.id] === 'string' ? existingMsgs[agent.id] : '',
+      });
+      if (p.isCancel(msg)) return cancelled();
+      resumeMessages[agent.id] = typeof msg === 'string' && msg.trim() ? msg : '';
+    }
+  }
+
+  // Merge over the existing file so a setup re-run keeps settings the wizard
+  // doesn't ask about (e.g. per-agent messages set via `unsnooze config`).
   writeConfig({
+    ...existing,
     autoResume, menuAutoAnswer, notifications, resumeMessage,
+    resumeMessages: { ...existingMsgs, ...resumeMessages },
     agents: Object.fromEntries(listAgents().map(a => [a.id, agents.includes(a.id)])),
   });