agent-noti 1.2.0 → 1.4.0

package/README.md

@@ -10,21 +10,141 @@ Works on macOS, Linux, and Windows.
 npm i -g agent-noti
 ```
 
-That's it. Hooks are added to both Claude Code and Codex automatically. Restart your agent.
+That's it. Hooks are added automatically and the interactive sound picker launches so you can choose a theme. Restart your agent.
 
 ## What it does
 
 | Event | Sound | Claude Code | Codex |
 |---|---|---|---|
-| Agent finished | `idle.mp3` | Stop | agent-turn-complete |
-| Needs your input | `input.mp3` | PermissionRequest | approval-requested |
+| Agent finished | idle sound | Stop | agent-turn-complete |
+| Needs your input | input sound | PermissionRequest | approval-requested |
+
+## Sound themes
+
+Each theme includes a separate idle and input sound.
+
+| Theme | Description |
+|---|---|
+| default | Original notification |
+| cow | Moo! |
+| goose | Honk! |
+| duck | Quack quack |
+| car | Vroom vroom |
+| slide-whistle | Wheee! |
+| video-game | Retro gaming |
+| digital-glass | Sleek & modern |
 
 ## Commands
 
 ```sh
-agent-noti test        # Play both sounds
-agent-noti install     # Re-add hooks (if needed)
-agent-noti uninstall   # Remove hooks
+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 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`.
+
+## Interactive picker
+
+```
+agent-noti pick
+```
+
+Navigate with arrow keys, preview sounds before selecting:
+
+- **Up / Down** — navigate themes
+- **Left** — play idle sound
+- **Right** — play input sound
+- **Enter** — select theme
+- **q** — quit
+
+The picker also includes **+ Add custom** at the bottom, which walks you through importing your own sound files. Once added, your custom sounds appear in the picker below default.
+
+## Custom sounds
+
+Run `agent-noti add-custom` (or select **+ Add custom** in the picker) for an interactive flow:
+
+1. Choose idle sound — enter a file path or skip (use default)
+2. Choose input sound — enter a file path, use same as idle, or skip
+
+Custom files are copied to `~/.agent-noti/sounds/` so they persist across package updates.
+
+## Volume & mute
+
+```sh
+agent-noti volume 5   # Set volume 1-10
+agent-noti volume     # Show current volume
+agent-noti mute       # Silence all notifications
+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
+- Send a test notification
+
+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.idle` | `true` | Notify on task complete |
+| `ntfy.input` | `true` | Notify on approval needed |
+
+## Config
+
+All settings are stored in `~/.agent-noti/config.json`:
+
+```json
+{
+  "idle": "cow",
+  "input": "cow",
+  "volume": 10,
+  "muted": false,
+  "ntfy": {
+    "enabled": true,
+    "server": "https://ntfy.sh",
+    "topic": "my-agent-alerts",
+    "priority": "default",
+    "idle": true,
+    "input": true
+  }
+}
 ```
 
 ## Uninstall
@@ -35,16 +155,12 @@ npm uninstall -g agent-noti
 
 Hooks are removed automatically.
 
-## Custom sounds
-
-Replace `sounds/idle.mp3` and `sounds/input.mp3` in the package directory with your own files.
-
 ## Platform support
 
 | OS | Audio player |
 |---|---|
 | macOS | `afplay` (built-in) |
-| Linux | `ffplay`, `paplay`, or `mpv` |
+| Linux | `ffplay`, `paplay`, or `mpv` (tries in order) |
 | Windows | PowerShell MediaPlayer |
 
 ## License

package/bin/cli.mjs

@@ -421,6 +421,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 +572,232 @@ 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",
+        idle: true,
+        input: true,
+      };
+      writeConfig(config);
+    }
+
+    const ntfyConf = config.ntfy;
+    const rows = ["idle", "input"];
+    let selected = 0;
+    let statusMsg = "";
+    const totalLines = 12;
+
+    function render(firstTime) {
+      if (!firstTime) process.stdout.write(`\x1b[${totalLines}A`);
+
+      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\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;
+
+      // 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 +838,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 +885,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 +898,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,6 +6,7 @@
  *        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";
@@ -69,36 +70,72 @@ 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();
-
-// Mute check (skip for --file, which is used by picker previews)
-if (arg !== "--file" && config.muted) process.exit(0);
+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 {}
+}
 
-const file = resolveSound(arg);
-if (!file) process.exit(1);
+(async () => {
+  const arg = process.argv[2];
+  if (!arg) process.exit(0);
 
-// 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 config = readConfig();
 
-const os = platform();
+  // Send ntfy push notification for actual events (not --file previews)
+  if (EVENTS.includes(arg)) {
+    await sendNtfy(arg, config);
+  }
 
-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/package.json

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