agent-noti 1.3.0 → 1.4.1

package/README.md

@@ -37,16 +37,18 @@ Each theme includes a separate idle and input sound.
 ## Commands
 
 ```sh
-agent-noti install        # Add hooks + pick theme     (i)
+agent-noti install        # Add hooks + pick theme       (i)
 agent-noti uninstall      # Remove hooks
-agent-noti test           # Play current sounds         (t)
-agent-noti sounds         # List available themes        (s)
-agent-noti pick           # Interactive sound picker     (p)
-agent-noti add-custom     # Use your own sound files     (ac)
-agent-noti volume <1-10>  # Set volume level             (v)
-agent-noti mute           # Mute notifications           (m)
-agent-noti unmute         # Unmute notifications         (u)
-agent-noti reset          # Reset everything             (r)
+agent-noti test           # Play current sounds           (t)
+agent-noti sounds         # List available themes          (s)
+agent-noti pick           # Interactive sound picker       (p)
+agent-noti add-custom     # Use your own sound files       (ac)
+agent-noti volume <1-10>  # Set volume level               (v)
+agent-noti mute           # Mute notifications             (m)
+agent-noti unmute         # Unmute notifications           (u)
+agent-noti ntfy           # Configure ntfy.sh push alerts  (n)
+agent-noti ntfy-test      # Send a test push notification  (nt)
+agent-noti reset          # Reset everything               (r)
 ```
 
 Every command has a short alias shown in parentheses — e.g. `agent-noti v 5` instead of `agent-noti volume 5`.
@@ -87,6 +89,46 @@ agent-noti unmute     # Re-enable notifications
 
 Setting volume while muted auto-unmutes. Volume works across all platforms.
 
+## Push notifications (ntfy.sh)
+
+Get push notifications on your phone or desktop via [ntfy.sh](https://ntfy.sh) — even when you're away from the terminal. ntfy works independently from audio: you can mute sounds and still receive push alerts.
+
+### Setup
+
+```sh
+agent-noti ntfy
+```
+
+This opens an interactive TUI where you can:
+- Set your ntfy server and topic
+- Toggle which events send push notifications (task complete / approval needed)
+- Set priority level and time threshold
+- Send a test notification
+
+The **threshold** setting (in minutes) skips push notifications for quick tasks. For example, set it to `5` and you'll only get pinged if the agent ran for at least 5 minutes. Set to `0` to always notify.
+
+On first run you'll be prompted for a topic name. Subscribe to the same topic in the [ntfy app](https://ntfy.sh) (Android/iOS/web) to receive notifications.
+
+### Quick test
+
+```sh
+agent-noti ntfy-test
+```
+
+Sends a test notification to your configured topic without opening the interactive TUI.
+
+### Config fields
+
+| Field | Default | Description |
+|---|---|---|
+| `ntfy.enabled` | `false` | Master on/off |
+| `ntfy.server` | `https://ntfy.sh` | ntfy server URL |
+| `ntfy.topic` | — | Your topic name (required) |
+| `ntfy.priority` | `default` | `min`, `low`, `default`, `high`, `urgent` |
+| `ntfy.threshold` | `0` | Min minutes before notifying (0 = always) |
+| `ntfy.idle` | `true` | Notify on task complete |
+| `ntfy.input` | `true` | Notify on approval needed |
+
 ## Config
 
 All settings are stored in `~/.agent-noti/config.json`:
@@ -96,7 +138,16 @@ All settings are stored in `~/.agent-noti/config.json`:
   "idle": "cow",
   "input": "cow",
   "volume": 10,
-  "muted": false
+  "muted": false,
+  "ntfy": {
+    "enabled": true,
+    "server": "https://ntfy.sh",
+    "topic": "my-agent-alerts",
+    "priority": "default",
+    "threshold": 5,
+    "idle": true,
+    "input": true
+  }
 }
 ```
 

package/bin/cli.mjs

@@ -9,6 +9,7 @@ import { homedir, platform } from "os";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const PLAY_SCRIPT = join(__dirname, "play.mjs");
+const STAMP_SCRIPT = join(__dirname, "stamp.mjs");
 const CODEX_NOTIFY_SCRIPT = join(__dirname, "codex-notify.mjs");
 const SOUNDS_DIR = join(__dirname, "..", "sounds");
 
@@ -98,9 +99,11 @@ function writeConfig(config) {
 function buildClaudeHooks() {
   const idle = { type: "command", command: `node "${PLAY_SCRIPT}" idle` };
   const input = { type: "command", command: `node "${PLAY_SCRIPT}" input` };
+  const stamp = { type: "command", command: `node "${STAMP_SCRIPT}"` };
   return {
     Stop: [{ hooks: [idle], metadata: { id: HOOK_ID } }],
     PermissionRequest: [{ hooks: [input], metadata: { id: HOOK_ID } }],
+    PromptSubmit: [{ hooks: [stamp], metadata: { id: HOOK_ID } }],
   };
 }
 
@@ -421,6 +424,14 @@ function sounds() {
   console.log("  Theme:  idle=%s, input=%s", idleLabel, inputLabel);
   const volBar = "#".repeat(vol) + "-".repeat(10 - vol);
   console.log(`  Volume: [${volBar}] ${vol}/10${muted ? "  (MUTED)" : ""}`);
+
+  if (config.ntfy && config.ntfy.topic) {
+    const n = config.ntfy;
+    const server = (n.server || "https://ntfy.sh").replace(/^https?:\/\//, "").replace(/\/+$/, "");
+    const status = n.enabled ? "enabled" : "disabled";
+    console.log(`  ntfy:   ${status} (${server}/${n.topic})`);
+  }
+
   console.log("");
 }
 
@@ -564,6 +575,244 @@ async function addCustom() {
   console.log("  Custom sounds applied.\n");
 }
 
+// --- ntfy.sh push notifications ---
+
+const NTFY_PRIORITIES = ["min", "low", "default", "high", "urgent"];
+
+function ntfyPrompt(label) {
+  return new Promise((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(`  ${label}`, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function ntfyInitialSetup() {
+  console.log("\n  First-time ntfy.sh setup\n");
+  const topic = await ntfyPrompt("Topic (required): ");
+  if (!topic) {
+    console.log("  Topic is required. Aborting.\n");
+    return null;
+  }
+  const server = await ntfyPrompt("Server (enter for https://ntfy.sh): ");
+  return { topic, server: server || "https://ntfy.sh" };
+}
+
+async function ntfySendTest(ntfyConfig) {
+  const server = (ntfyConfig.server || "https://ntfy.sh").replace(/\/+$/, "");
+  const url = `${server}/${ntfyConfig.topic}`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      Title: "Test Notification",
+      Priority: ntfyConfig.priority || "default",
+      Tags: "bell",
+    },
+    body: "agent-noti test notification",
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+}
+
+function ntfy() {
+  return new Promise(async (resolve) => {
+    if (!process.stdin.isTTY) {
+      console.log("\n  This command requires an interactive terminal.\n");
+      resolve();
+      return;
+    }
+
+    const config = readConfig();
+
+    // First-time setup: prompt for topic
+    if (!config.ntfy || !config.ntfy.topic) {
+      const setup = await ntfyInitialSetup();
+      if (!setup) { resolve(); return; }
+      config.ntfy = {
+        enabled: true,
+        server: setup.server,
+        topic: setup.topic,
+        priority: "default",
+        threshold: 0,
+        idle: true,
+        input: true,
+      };
+      writeConfig(config);
+    }
+
+    const ntfyConf = config.ntfy;
+    const rows = ["idle", "input"];
+    let selected = 0;
+    let statusMsg = "";
+    const totalLines = 13;
+
+    function render(firstTime) {
+      if (!firstTime) process.stdout.write(`\x1b[${totalLines}A`);
+
+      const thresh = ntfyConf.threshold ?? 0;
+      const threshLabel = thresh === 0 ? "off (always notify)" : `${thresh} min`;
+
+      process.stdout.write("\x1b[2K\n");
+      process.stdout.write(`\x1b[2K  \x1b[1mntfy.sh push notifications\x1b[0m\n`);
+      process.stdout.write("\x1b[2K\n");
+      process.stdout.write(`\x1b[2K  Server:    \x1b[36m${ntfyConf.server || "https://ntfy.sh"}\x1b[0m\n`);
+      process.stdout.write(`\x1b[2K  Topic:     \x1b[36m${ntfyConf.topic}\x1b[0m\n`);
+      process.stdout.write(`\x1b[2K  Priority:  \x1b[36m${ntfyConf.priority || "default"}\x1b[0m\n`);
+      process.stdout.write(`\x1b[2K  Threshold: \x1b[36m${threshLabel}\x1b[0m\n`);
+      process.stdout.write("\x1b[2K\n");
+
+      for (let i = 0; i < rows.length; i++) {
+        const checked = ntfyConf[rows[i]] ? "x" : " ";
+        const label = rows[i] === "idle" ? "Notify on task complete (idle)" : "Notify on approval needed (input)";
+        const arrow = i === selected ? "\x1b[36m> " : "  ";
+        const color = i === selected ? "\x1b[36m" : "\x1b[0m";
+        process.stdout.write(`\x1b[2K  ${arrow}${color}[${checked}] ${label}\x1b[0m\n`);
+      }
+
+      process.stdout.write("\x1b[2K\n");
+      const status = statusMsg ? `  ${statusMsg}` : "";
+      process.stdout.write(`\x1b[2K  \x1b[90m[space] Toggle  [up/down] Navigate  [e] Edit  [t] Test  [q] Save & quit\x1b[0m${status}\n`);
+      process.stdout.write(`\x1b[2K\n`);
+    }
+
+    const stdin = process.stdin;
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+
+    render(true);
+
+    function cleanup() {
+      stdin.removeListener("data", onKey);
+      stdin.setRawMode(false);
+      stdin.pause();
+    }
+
+    function save() {
+      ntfyConf.enabled = ntfyConf.idle || ntfyConf.input;
+      config.ntfy = ntfyConf;
+      writeConfig(config);
+    }
+
+    async function editFields() {
+      cleanup();
+      console.log("");
+
+      const newServer = await ntfyPrompt(`Server (${ntfyConf.server || "https://ntfy.sh"}): `);
+      if (newServer) ntfyConf.server = newServer;
+
+      const newTopic = await ntfyPrompt(`Topic (${ntfyConf.topic}): `);
+      if (newTopic) ntfyConf.topic = newTopic;
+
+      const priIdx = NTFY_PRIORITIES.indexOf(ntfyConf.priority || "default");
+      const newPri = await ntfyPrompt(`Priority [${NTFY_PRIORITIES.join("/")}] (${NTFY_PRIORITIES[priIdx]}): `);
+      if (newPri && NTFY_PRIORITIES.includes(newPri)) ntfyConf.priority = newPri;
+
+      const curThresh = ntfyConf.threshold ?? 0;
+      const newThresh = await ntfyPrompt(`Threshold in minutes, 0=off (${curThresh}): `);
+      if (newThresh !== "") {
+        const val = parseInt(newThresh, 10);
+        if (!isNaN(val) && val >= 0) ntfyConf.threshold = val;
+      }
+
+      // Re-enter raw mode and re-render
+      stdin.setRawMode(true);
+      stdin.resume();
+      stdin.setEncoding("utf8");
+      stdin.on("data", onKey);
+      render(true);
+    }
+
+    async function testNotification() {
+      cleanup();
+      statusMsg = "\x1b[33mSending...\x1b[0m";
+      // Re-enter raw mode to render
+      stdin.setRawMode(true);
+      stdin.resume();
+      stdin.setEncoding("utf8");
+      render(true);
+
+      try {
+        await ntfySendTest(ntfyConf);
+        statusMsg = "\x1b[32mSent!\x1b[0m";
+      } catch (e) {
+        statusMsg = `\x1b[31mFailed: ${e.message}\x1b[0m`;
+      }
+
+      stdin.on("data", onKey);
+      render();
+      setTimeout(() => { statusMsg = ""; render(); }, 3000);
+    }
+
+    async function onKey(key) {
+      if (key === "\x03") {
+        cleanup();
+        save();
+        console.log("");
+        process.exit(0);
+      }
+
+      if (key === "q" || key === "Q" || key === "\r" || key === "\n") {
+        cleanup();
+        save();
+        console.log(`\n  ntfy config saved (${ntfyConf.enabled ? "enabled" : "disabled"}).\n`);
+        resolve();
+        return;
+      }
+
+      if (key === " ") {
+        ntfyConf[rows[selected]] = !ntfyConf[rows[selected]];
+        render();
+        return;
+      }
+
+      if (key === "\x1b[A" || key === "k") {
+        selected = (selected - 1 + rows.length) % rows.length;
+        render();
+        return;
+      }
+
+      if (key === "\x1b[B" || key === "j") {
+        selected = (selected + 1) % rows.length;
+        render();
+        return;
+      }
+
+      if (key === "e" || key === "E") {
+        await editFields();
+        return;
+      }
+
+      if (key === "t" || key === "T") {
+        stdin.removeListener("data", onKey);
+        await testNotification();
+        return;
+      }
+    }
+
+    stdin.on("data", onKey);
+  });
+}
+
+async function ntfyTest() {
+  const config = readConfig();
+  const ntfyConf = config.ntfy;
+
+  if (!ntfyConf || !ntfyConf.topic) {
+    console.log("\n  ntfy not configured. Run 'agent-noti ntfy' first.\n");
+    return;
+  }
+
+  process.stdout.write("\n  Sending test notification...");
+  try {
+    await ntfySendTest(ntfyConf);
+    console.log(" sent!\n");
+  } catch (e) {
+    console.log(` failed: ${e.message}\n`);
+  }
+}
+
 function mute() {
   const config = readConfig();
   config.muted = true;
@@ -604,7 +853,7 @@ function volume(args) {
 
 function reset() {
   writeConfig({ idle: "default", input: "default", volume: 10, muted: false });
-  console.log("\n  Reset to defaults (theme=default, volume=10, unmuted).\n");
+  console.log("\n  Reset to defaults (theme=default, volume=10, unmuted, ntfy cleared).\n");
 }
 
 function applyPickerChoice(choice) {
@@ -651,6 +900,8 @@ async function main() {
     case "mute":     case "m":  mute(); break;
     case "unmute":   case "u":  unmute(); break;
     case "reset":    case "r":  reset(); break;
+    case "ntfy":     case "n":  await ntfy(); break;
+    case "ntfy-test": case "nt": await ntfyTest(); break;
     default:
       console.log("");
       console.log("  agent-noti install   (i)   Add hooks + pick theme");
@@ -662,6 +913,8 @@ async function main() {
       console.log("  agent-noti volume    (v)   Set volume <1-10>");
       console.log("  agent-noti mute      (m)   Mute notifications");
       console.log("  agent-noti unmute    (u)   Unmute notifications");
+      console.log("  agent-noti ntfy      (n)   Configure ntfy.sh push notifications");
+      console.log("  agent-noti ntfy-test (nt)  Send a test push notification");
       console.log("  agent-noti reset     (r)   Reset everything");
       console.log("");
   }

package/bin/play.mjs

@@ -6,17 +6,21 @@
  *        node play.mjs --file <path>       — plays a file directly
  *
  * Respects ~/.agent-noti/config.json for mute and volume (1-10).
+ * Also sends ntfy.sh push notifications when configured.
  */
 
 import { execFile, exec } from "child_process";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { platform, homedir } from "os";
-import { existsSync, readFileSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const SOUNDS_DIR = join(__dirname, "..", "sounds");
-const CONFIG_PATH = join(homedir(), ".agent-noti", "config.json");
+const CONFIG_DIR = join(homedir(), ".agent-noti");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+const LAST_PROMPT_PATH = join(CONFIG_DIR, "last-prompt");
+const LAST_EVENT_PATH = join(CONFIG_DIR, "last-event");
 
 const EVENTS = ["idle", "input"];
 
@@ -69,36 +73,98 @@ function resolveSound(arg) {
   return findFile(`${arg}-idle`) || findFile(arg) || null;
 }
 
-const arg = process.argv[2];
-if (!arg) process.exit(0);
+const NTFY_MESSAGES = {
+  idle: { title: "Task Complete", tags: "white_check_mark", body: "Agent finished task" },
+  input: { title: "Approval Needed", tags: "warning", body: "Agent needs your approval" },
+};
 
-const config = readConfig();
+async function sendNtfy(event, config) {
+  try {
+    const ntfy = config.ntfy;
+    if (!ntfy || !ntfy.enabled || !ntfy.topic) return;
+    if (!ntfy[event]) return;
+
+    const msg = NTFY_MESSAGES[event];
+    if (!msg) return;
+
+    const server = (ntfy.server || "https://ntfy.sh").replace(/\/+$/, "");
+    const url = `${server}/${ntfy.topic}`;
+
+    await fetch(url, {
+      method: "POST",
+      headers: {
+        Title: msg.title,
+        Priority: ntfy.priority || "default",
+        Tags: msg.tags,
+      },
+      body: msg.body,
+    });
+  } catch {}
+}
+
+(async () => {
+  const arg = process.argv[2];
+  if (!arg) process.exit(0);
 
-// Mute check (skip for --file, which is used by picker previews)
-if (arg !== "--file" && config.muted) process.exit(0);
+  const config = readConfig();
 
-const file = resolveSound(arg);
-if (!file) process.exit(1);
+  // Send ntfy push notification for actual events (not --file previews)
+  if (EVENTS.includes(arg)) {
+    const threshold = config.ntfy?.threshold ?? 0; // minutes, 0 = always
+    let shouldSend = true;
+
+    if (threshold > 0) {
+      // Claude Code: PromptSubmit hook writes last-prompt (exact task start)
+      // Codex fallback: use last-event (time since previous event)
+      const tsFile = existsSync(LAST_PROMPT_PATH) ? LAST_PROMPT_PATH : LAST_EVENT_PATH;
+      try {
+        if (existsSync(tsFile)) {
+          const started = parseInt(readFileSync(tsFile, "utf-8"), 10);
+          if (!isNaN(started)) {
+            const elapsed = (Date.now() - started) / 60000;
+            shouldSend = elapsed >= threshold;
+          }
+        }
+      } catch {}
+    }
 
-// Volume: 1-10 config → 0.0-1.0 native scale
-const vol = Math.max(1, Math.min(10, config.volume ?? 10));
-const volFloat = vol / 10;   // 0.1 – 1.0  (macOS, Windows)
-const volPct = vol * 10;     // 10  – 100   (Linux ffplay, mpv)
-const volPulse = Math.round(volFloat * 65536); // paplay scale
+    if (shouldSend) {
+      await sendNtfy(arg, config);
+    }
 
-const os = platform();
+    // Write last-event timestamp (Codex fallback for threshold)
+    try {
+      mkdirSync(CONFIG_DIR, { recursive: true });
+      writeFileSync(LAST_EVENT_PATH, String(Date.now()));
+    } catch {}
+  }
 
-if (os === "darwin") {
-  execFile("afplay", ["-v", String(volFloat), file], () => {});
-} else if (os === "win32") {
-  exec(
-    `powershell -NoProfile -Command "Add-Type -AssemblyName PresentationCore; $p = New-Object System.Windows.Media.MediaPlayer; $p.Open([uri]'${file.replace(/'/g, "''")}'); $p.Volume = ${volFloat}; $p.Play(); Start-Sleep -Seconds 3"`,
-    () => {}
-  );
-} else {
-  execFile("ffplay", ["-nodisp", "-autoexit", "-loglevel", "quiet", "-volume", String(volPct), file], (err) => {
-    if (err) execFile("paplay", ["--volume", String(volPulse), file], (err2) => {
-      if (err2) execFile("mpv", ["--no-video", `--volume=${volPct}`, file], () => {});
+  // Mute check (skip for --file, which is used by picker previews)
+  if (arg !== "--file" && config.muted) process.exit(0);
+
+  const file = resolveSound(arg);
+  if (!file) process.exit(1);
+
+  // Volume: 1-10 config → 0.0-1.0 native scale
+  const vol = Math.max(1, Math.min(10, config.volume ?? 10));
+  const volFloat = vol / 10;   // 0.1 – 1.0  (macOS, Windows)
+  const volPct = vol * 10;     // 10  – 100   (Linux ffplay, mpv)
+  const volPulse = Math.round(volFloat * 65536); // paplay scale
+
+  const os = platform();
+
+  if (os === "darwin") {
+    execFile("afplay", ["-v", String(volFloat), file], () => {});
+  } else if (os === "win32") {
+    exec(
+      `powershell -NoProfile -Command "Add-Type -AssemblyName PresentationCore; $p = New-Object System.Windows.Media.MediaPlayer; $p.Open([uri]'${file.replace(/'/g, "''")}'); $p.Volume = ${volFloat}; $p.Play(); Start-Sleep -Seconds 3"`,
+      () => {}
+    );
+  } else {
+    execFile("ffplay", ["-nodisp", "-autoexit", "-loglevel", "quiet", "-volume", String(volPct), file], (err) => {
+      if (err) execFile("paplay", ["--volume", String(volPulse), file], (err2) => {
+        if (err2) execFile("mpv", ["--no-video", `--volume=${volPct}`, file], () => {});
+      });
     });
-  });
-}
+  }
+})();

package/bin/stamp.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Records the current timestamp to ~/.agent-noti/last-prompt.
+ * Called by the PromptSubmit hook so play.mjs can measure task duration.
+ */
+
+import { writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const dir = join(homedir(), ".agent-noti");
+mkdirSync(dir, { recursive: true });
+writeFileSync(join(dir, "last-prompt"), String(Date.now()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-noti",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "description": "Audio notifications for Claude Code & Codex — customizable sound themes",
   "bin": {
     "agent-noti": "./bin/cli.mjs"