ai-notify 0.1.0

package/recipes/swiftbar/ai-notify.3s.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Menu bar indicator + toggle for ai-notify, via SwiftBar (or xbar).
+#
+# This is the recommended setup: an always-visible 🔔 / 🔕 in the macOS menu
+# bar that you click to mute everything — no terminal needed, state always shown.
+#
+# Install:
+#   1. brew install --cask swiftbar      (or xbar)
+#   2. Copy this file into your SwiftBar plugin folder, keep the ".3s.sh"
+#      suffix (refreshes every 3s), and make it executable:
+#        chmod +x ai-notify.3s.sh
+#   3. The icon appears in your menu bar. Click it → "Toggle mute".
+
+export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:$PATH"
+
+ICON=$(ai-notify status --icon 2>/dev/null || echo "❓")
+
+# Menu bar title (just the glyph)
+echo "$ICON"
+echo "---"
+# Dropdown actions. terminal=false runs silently; refresh=true re-renders the icon.
+echo "Toggle mute | bash=ai-notify param1=toggle terminal=false refresh=true"
+echo "Show status | bash=ai-notify param1=status terminal=true"

package/recipes/tmux/README.md

@@ -0,0 +1,37 @@
+# Show mute state in your tmux / shell prompt
+
+If you live in tmux, put the indicator in the status bar — always visible,
+across every pane, even while agents run.
+
+`~/.tmux.conf`:
+
+```tmux
+set -g status-interval 3
+set -ga status-right '#(ai-notify status --icon) '
+```
+
+Bind a key to toggle without leaving tmux (here: prefix + N):
+
+```tmux
+bind N run-shell 'ai-notify toggle'
+```
+
+## Shell prompt (zsh)
+
+Show `🔕` in your prompt only when muted:
+
+```zsh
+ai_notify_indicator() { [ "$(ai-notify status --plain)" = muted ] && echo "🔕 "; }
+setopt PROMPT_SUBST
+PROMPT='$(ai_notify_indicator)'$PROMPT
+```
+
+## Starship
+
+```toml
+# ~/.config/starship.toml
+[custom.ai_notify]
+command = "ai-notify status --icon"
+when = true
+format = "[$output]($style) "
+```

package/src/cli.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+// ai-notify — desktop/sound notifications for terminal AI coding agents.
+// One mute switch for all of them, across every terminal. No daemon.
+
+import { readFileSync } from 'node:fs';
+import { providers, byId } from './providers/index.mjs';
+import { emit } from './notify.mjs';
+import { deriveLabel, cliInvocation, isEphemeralInstall } from './util.mjs';
+import { curatedVoices, resolveVoice, previewVoice } from './voices.mjs';
+import * as menubar from './menubar.mjs';
+import { translate } from './translate.mjs';
+import { isMuted, setMuted, toggleMuted, readConfig, writeConfig, paths, DEFAULT_CONFIG } from './state.mjs';
+
+const VERSION = '0.1.0';
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+
+// Tiny flag parser: --key value / --flag
+const opt = (name, fallback = undefined) => {
+  const i = args.indexOf(`--${name}`);
+  if (i === -1) return fallback;
+  const next = args[i + 1];
+  return next && !next.startsWith('--') ? next : true;
+};
+const positionals = args.slice(1).filter((a) => !a.startsWith('--'));
+
+const log = (...m) => console.log(...m);
+const onlyFilter = () => {
+  const only = opt('only');
+  return typeof only === 'string' ? only.split(',').map((s) => s.trim()) : null;
+};
+const selected = () => {
+  const only = onlyFilter();
+  return providers.filter((p) => (only ? only.includes(p.id) : true));
+};
+
+const readStdinJson = () => {
+  try {
+    return JSON.parse(readFileSync(0, 'utf8'));
+  } catch {
+    return {};
+  }
+};
+
+const cmds = {
+  init() {
+    const dryRun = !!opt('dry-run');
+    const { node, cliPath } = cliInvocation();
+    if (isEphemeralInstall(cliPath)) {
+      log('⚠  Running from a temporary npx cache. Hooks need a persistent install.');
+      log('   Install first:  npm i -g ai-notify   then:  ai-notify init\n');
+    }
+    log(dryRun ? 'Preview (no changes written):\n' : 'Wiring detected agents:\n');
+    let any = false;
+    for (const p of selected()) {
+      if (!p.detect()) continue;
+      any = true;
+      const r = p.wire({ node, cliPath, dryRun });
+      const icon = r.skipped ? '⚠ ' : r.changed ? '✓ ' : '· ';
+      log(`  ${icon}${p.displayName}: ${r.detail}`);
+    }
+    if (!any) log('  No supported agents detected (looked for Claude Code, Codex, Gemini).');
+    log(`\nMute toggle:  ai-notify toggle    Status:  ai-notify status`);
+    if (!dryRun) log('Restart already-running Codex sessions to pick up the change.');
+  },
+
+  uninstall() {
+    const dryRun = !!opt('dry-run');
+    log('Removing ai-notify wiring:\n');
+    for (const p of selected()) {
+      const r = p.unwire({ dryRun });
+      log(`  ${r.changed ? '✓ ' : '· '}${p.displayName}: ${r.detail}`);
+    }
+  },
+
+  on() { setMuted(false); log('🔔 notifications ON'); emitConfirm(); },
+  off() { setMuted(true); log('🔕 notifications OFF (muted)'); },
+  toggle() {
+    const muted = toggleMuted();
+    log(muted ? '🔕 notifications OFF (muted)' : '🔔 notifications ON');
+    if (!muted) emitConfirm();
+  },
+  status() {
+    // Compact forms for embedding in menu bars, prompts, tmux, and the
+    // Claude Code statusline — where you can't type a command but want the
+    // state always visible.
+    if (opt('icon')) return log(isMuted() ? '🔕' : '🔔');
+    if (opt('plain')) return log(isMuted() ? 'muted' : 'on');
+
+    log(`notifications: ${isMuted() ? '🔕 OFF (muted)' : '🔔 ON'}`);
+    log(`flag:   ${paths.muteFlagPath()}`);
+    log(`config: ${paths.configPath()}\n`);
+    for (const p of providers) {
+      const s = p.status();
+      if (!s.installed) continue;
+      log(`  ${p.displayName.padEnd(14)} ${s.wired ? '✓ wired' : '✗ not wired'}`);
+    }
+  },
+
+  doctor() {
+    log(`ai-notify ${VERSION}  (node ${process.version}, ${process.platform})\n`);
+    const { cliPath } = cliInvocation();
+    if (isEphemeralInstall(cliPath)) log('⚠  ephemeral npx install — run `npm i -g ai-notify` for hooks to persist.\n');
+    log('Agents:');
+    for (const p of providers) {
+      const s = p.status();
+      log(`  ${p.displayName.padEnd(14)} ${!s.installed ? '— not installed' : s.wired ? '✓ wired' : '✗ detected, not wired'}`);
+    }
+  },
+
+  config() {
+    if (positionals[0] === 'init') {
+      const file = writeConfig(readConfig());
+      log(`wrote ${file}`);
+    } else {
+      log(JSON.stringify(readConfig(), null, 2));
+    }
+  },
+
+  // Pick the spoken read-out voice from the machine's built-in `say` voices.
+  // Offline, free, no API. Different voice per task = tell terminals apart.
+  voice() {
+    const sub = positionals[0];
+    const config = readConfig();
+    const list = curatedVoices(10);
+    const sample =
+      (config.doneMessage || 'finished').replace(/\{label\}/g, 'ai-notify').replace(/\s+/g, ' ').trim() ||
+      'finished';
+
+    const setVoice = (name) => {
+      config.voice = name; // '' = OS default
+      // Global voice wins only if no per-provider override; clear them so the
+      // single switch actually takes effect everywhere.
+      for (const k of Object.keys(config.providers || {})) {
+        if (config.providers[k]) delete config.providers[k].voice;
+      }
+      writeConfig(config);
+    };
+
+    if (sub === 'preview' || sub === 'test' || sub === 'all') {
+      if (!list.length) return log('No `say` voices found (this is a macOS feature).');
+      log('Previewing voices — listen, then:  ai-notify voice <number>\n');
+      list.forEach((n, i) => {
+        log(`  ${String(i + 1).padStart(2)}. ${n}`);
+        previewVoice(n, `${i + 1}番。${n}。${sample}`);
+      });
+      return;
+    }
+
+    if (sub === 'default' || sub === 'off' || sub === 'reset' || sub === 'none') {
+      setVoice('');
+      return log('Voice reset to the OS default.');
+    }
+
+    if (sub) {
+      const picked = resolveVoice(sub, list);
+      if (!picked) {
+        console.error(`unknown voice: ${sub}   (see: ai-notify voice)`);
+        process.exit(1);
+      }
+      setVoice(picked);
+      log(`🔊 voice → ${picked}`);
+      previewVoice(picked, sample);
+      return;
+    }
+
+    // No arg: list the menu.
+    if (!list.length) {
+      log('No `say` voices found — voice selection is a macOS feature.');
+      log('On other platforms, set "voice" in config.json to any name your TTS accepts.');
+      return;
+    }
+    const current = config.voice || '(OS default)';
+    log(`Current voice: ${current}\n`);
+    list.forEach((n, i) => log(`  ${String(i + 1).padStart(2)}. ${n}${n === config.voice ? '   ← current' : ''}`));
+    log('\n  Choose:   ai-notify voice <number|name>');
+    log('  Hear all: ai-notify voice preview');
+    log('  Reset:    ai-notify voice default');
+  },
+
+  // Native menu bar bell (macOS). Self-contained — no Hammerspoon/SwiftBar.
+  menubar() {
+    const sub = positionals[0] || 'status';
+    if (!menubar.isMac()) return log('The menu bar agent is macOS-only.');
+
+    if (sub === 'install') {
+      log('Installing the ai-notify menu bar agent…');
+      if (!menubar.isBuilt()) log('  building the app (system Swift)…');
+      const r = menubar.install();
+      log(`  ✓ app:   ${r.app}`);
+      log(`  ✓ agent: ${r.plist} (starts at login)`);
+      log('A 🔔 should now be in your menu bar. Left-click toggles, right-click for a menu.');
+      return;
+    }
+    if (sub === 'uninstall') {
+      menubar.uninstall();
+      log('✓ Removed the menu bar agent (LaunchAgent unloaded, app stopped).');
+      return;
+    }
+    if (sub === 'build') {
+      log(`✓ built: ${menubar.build()}`);
+      return;
+    }
+    // status
+    log(`menu bar agent:`);
+    log(`  built:     ${menubar.isBuilt() ? '✓' : '— (run: ai-notify menubar build)'}`);
+    log(`  installed: ${menubar.isInstalled() ? '✓ (auto-start at login)' : '—'}`);
+    log(`  running:   ${menubar.isRunning() ? '✓' : '—'}`);
+    if (!menubar.isInstalled()) log('\nEnable it:  ai-notify menubar install');
+  },
+
+  // Translate the agent's spoken message into your language before speaking it.
+  // Key-less and free (one HTTP request, no dependency); falls back to your
+  // templates if offline.
+  translate() {
+    const sub = positionals[0] || 'status';
+    const config = readConfig();
+
+    if (sub === 'on') {
+      const lang = positionals[1] || 'ja';
+      config.translateTo = lang;
+      config.speakAgentMessage = true; // we must keep the message to translate it
+      writeConfig(config);
+      log(`✓ translation on → ${lang}. Testing…`);
+      const out = translate('The task is done. I updated three files.', lang, 8000);
+      log(out ? `  EN→ ${out}` : '  ⚠ no result (offline?). Falls back to your templates.');
+      return;
+    }
+    if (sub === 'off' || sub === 'none') {
+      config.translateTo = '';
+      writeConfig(config);
+      return log('Translation off.');
+    }
+    if (sub === 'test') {
+      const lang = config.translateTo || 'ja';
+      const text = positionals.slice(1).join(' ') || 'Claude needs your permission to run a command.';
+      const out = translate(text, lang, 8000);
+      log(out ? `EN  ${text}\n${lang.toUpperCase()}  ${out}` : '⚠ no result (offline?)');
+      return;
+    }
+    // status
+    log(`translation: ${config.translateTo ? `on → ${config.translateTo}` : 'off'}`);
+    if (!config.translateTo) log('Enable:  ai-notify translate on ja');
+  },
+
+  hook() {
+    const source = opt('source', 'default');
+    let event = opt('event', 'done');
+    let cwd = '';
+    let message = '';
+
+    if (source === 'codex') {
+      // Codex passes a single JSON argument.
+      let data = {};
+      try { data = JSON.parse(positionals[0] || '{}'); } catch { /* ignore */ }
+      if (data.type && data.type !== 'agent-turn-complete') process.exit(0);
+      cwd = data.cwd || '';
+      message = data['last-assistant-message'] || '';
+      event = 'done';
+    } else {
+      // Claude (and the generic case) pass JSON on stdin.
+      const data = readStdinJson();
+      cwd = data.cwd || '';
+      message = data.message || '';
+    }
+
+    const label = deriveLabel(cwd);
+    emit({ provider: byId(source) ? source : 'default', event, label, message });
+  },
+
+  version() { log(VERSION); },
+  help() { printHelp(); },
+};
+
+function emitConfirm() {
+  emit({ provider: 'default', event: 'done', label: 'ai-notify', message: readConfig().onMessage });
+}
+
+function printHelp() {
+  log(`ai-notify ${VERSION} — notifications for terminal AI coding agents
+
+Usage:
+  ai-notify init [--dry-run] [--only claude,codex]   wire detected agents
+  ai-notify uninstall [--only ...]                   remove wiring
+  ai-notify toggle | on | off | status               control the mute switch
+  ai-notify voice [number|name|preview|default]      pick the spoken voice
+  ai-notify menubar [install|uninstall|status]       native menu bar bell (macOS)
+  ai-notify translate [on <lang>|off|test]           speak agent text in your language
+  ai-notify doctor                                    check deps & wiring
+  ai-notify config [init]                             print (or write) config
+
+Per-window overrides (export in a terminal before launching the agent):
+  AI_NOTIFY_VOICE=Eddy    give this window/pane its own spoken voice
+  AI_NOTIFY_LABEL=api     name this window in the spoken/banner read-out
+
+Make it one tap: bind a hotkey / menubar button to \`ai-notify toggle\`
+(see recipes/ for macOS Shortcuts, Raycast, Stream Deck).`);
+}
+
+const handler =
+  cmds[cmd] ||
+  (cmd === '-v' || cmd === '--version' ? cmds.version : null) ||
+  (cmd === undefined || cmd === '-h' || cmd === '--help' ? cmds.help : null);
+
+if (!handler) {
+  console.error(`unknown command: ${cmd}\n`);
+  printHelp();
+  process.exit(1);
+}
+handler();

package/src/menubar.mjs

@@ -0,0 +1,97 @@
+// Native menu bar agent management (macOS).
+//
+// Ships a tiny self-contained NSStatusItem app (menubar/) and runs it as a
+// per-user LaunchAgent so a live 🔔/🔕 appears in the menu bar — with NO
+// third-party app (Hammerspoon/SwiftBar/etc.) required.
+//
+// The app and the CLI share one truth: the mute flag file. No IPC, no daemon
+// beyond this one lightweight GUI agent.
+
+import { homedir, platform } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { execFileSync, spawnSync } from 'node:child_process';
+
+export const LABEL = 'com.ai-notify.menubar';
+
+const pkgRoot = () => dirname(dirname(fileURLToPath(import.meta.url))); // .../ai-notify
+const menubarDir = () => join(pkgRoot(), 'menubar');
+export const appPath = () => join(menubarDir(), 'dist', 'ai-notify.app');
+const exePath = () => join(appPath(), 'Contents', 'MacOS', 'ai-notify-menubar');
+const plistPath = () => join(homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`);
+
+export const isMac = () => platform() === 'darwin';
+export const isBuilt = () => existsSync(exePath());
+export const isInstalled = () => existsSync(plistPath());
+
+export const isRunning = () => {
+  const r = spawnSync('pgrep', ['-f', 'ai-notify-menubar'], { encoding: 'utf8' });
+  return r.status === 0 && r.stdout.trim().length > 0;
+};
+
+// Build the .app from source with the system Swift toolchain (no Xcode project).
+export const build = () => {
+  const script = join(menubarDir(), 'build.sh');
+  if (!existsSync(script)) throw new Error('menubar/build.sh missing');
+  execFileSync('bash', [script], { stdio: 'inherit' });
+  return appPath();
+};
+
+const writePlist = () => {
+  const dir = dirname(plistPath());
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${exePath()}</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>ProcessType</key><string>Interactive</string>
+  <key>LimitLoadToSessionType</key><string>Aqua</string>
+</dict>
+</plist>
+`;
+  writeFileSync(plistPath(), xml);
+};
+
+const launchctl = (...args) => spawnSync('launchctl', args, { encoding: 'utf8' });
+
+const killExisting = () => spawnSync('pkill', ['-f', 'ai-notify-menubar']);
+
+// Load (and start) the agent. Tries the modern domain API, falls back to legacy.
+const load = () => {
+  const uid = process.getuid();
+  killExisting(); // avoid a duplicate icon if one was launched by hand
+  let r = launchctl('bootstrap', `gui/${uid}`, plistPath());
+  if (r.status !== 0) r = launchctl('load', '-w', plistPath());
+  launchctl('kickstart', '-k', `gui/${uid}/${LABEL}`);
+  return r;
+};
+
+const unload = () => {
+  const uid = process.getuid();
+  let r = launchctl('bootout', `gui/${uid}/${LABEL}`);
+  if (r.status !== 0) r = launchctl('unload', '-w', plistPath());
+  killExisting();
+  return r;
+};
+
+export const install = () => {
+  if (!isMac()) throw new Error('the menu bar agent is macOS-only');
+  if (!isBuilt()) build();
+  writePlist();
+  load();
+  return { app: appPath(), plist: plistPath() };
+};
+
+export const uninstall = () => {
+  if (isInstalled()) unload();
+  else killExisting();
+  if (existsSync(plistPath())) rmSync(plistPath());
+  return { plist: plistPath() };
+};

package/src/notify.mjs

@@ -0,0 +1,133 @@
+// Cross-platform notifier: sound + spoken read-out + desktop banner.
+//
+// Every emitter is best-effort and degrades silently when a backend is missing,
+// so a Linux box without `notify-send` (or a Mac without `terminal-notifier`)
+// never errors — it just does what it can.
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { isMuted, readConfig } from './state.mjs';
+import { translate } from './translate.mjs';
+
+const platform = process.platform; // 'darwin' | 'linux' | 'win32'
+
+const run = (cmd, args) => {
+  try {
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: false });
+    child.on('error', () => {}); // missing binary -> ignore
+  } catch {
+    /* ignore */
+  }
+};
+
+const which = (bin) =>
+  (process.env.PATH || '')
+    .split(':')
+    .some((dir) => dir && existsSync(`${dir}/${bin}`));
+
+// Resolve a configured sound name to something the OS can play.
+const resolveSound = (name) => {
+  if (!name) return null;
+  if (name.includes('/')) return name; // already an absolute/relative path
+  if (platform === 'darwin') return `/System/Library/Sounds/${name}.aiff`;
+  return name; // linux/win: treated as a freedesktop event id / ignored
+};
+
+const playSound = (name) => {
+  const sound = resolveSound(name);
+  if (platform === 'darwin') {
+    if (sound && existsSync(sound)) {
+      // play twice, a touch louder, so it is hard to miss
+      run('afplay', ['-v', '2', sound]);
+      run('afplay', ['-v', '2', sound]);
+    }
+  } else if (platform === 'linux') {
+    if (which('paplay') && existsSync('/usr/share/sounds/freedesktop/stereo/complete.oga')) {
+      run('paplay', ['/usr/share/sounds/freedesktop/stereo/complete.oga']);
+    } else if (which('canberra-gtk-play')) {
+      run('canberra-gtk-play', ['-i', 'complete']);
+    } else if (which('aplay')) {
+      run('aplay', ['-q', '/usr/share/sounds/alsa/Front_Center.wav']);
+    }
+  } else if (platform === 'win32') {
+    run('powershell', ['-NoProfile', '-Command', '[console]::beep(880,200)']);
+  }
+};
+
+const speak = (text, voice) => {
+  if (!text) return;
+  if (platform === 'darwin') {
+    run('say', voice ? ['-v', voice, text] : [text]);
+  } else if (platform === 'linux') {
+    if (which('spd-say')) run('spd-say', [text]);
+    else if (which('espeak')) run('espeak', [text]);
+  } else if (platform === 'win32') {
+    run('powershell', [
+      '-NoProfile',
+      '-Command',
+      `Add-Type -AssemblyName System.Speech; (New-Object System.Speech.Synthesis.SpeechSynthesizer).Speak('${text.replace(/'/g, '')}')`,
+    ]);
+  }
+};
+
+const banner = (title, subtitle, message) => {
+  if (platform === 'darwin') {
+    if (which('terminal-notifier')) {
+      run('terminal-notifier', ['-title', title, '-subtitle', subtitle, '-message', message]);
+    } else {
+      const esc = (s) => String(s).replace(/"/g, '\\"');
+      run('osascript', ['-e', `display notification "${esc(message)}" with title "${esc(title)}" subtitle "${esc(subtitle)}"`]);
+    }
+  } else if (platform === 'linux') {
+    if (which('notify-send')) run('notify-send', [`${title}: ${subtitle}`, message]);
+  }
+  // win32: skipped (no dependency-free toast); sound/voice still fire.
+};
+
+// Public entry. Called by the hook handler with already-parsed fields.
+export const emit = ({ provider = 'default', event = 'done', label = '', message = '' }) => {
+  const config = readConfig();
+  const muted = isMuted();
+  const p = config.providers[provider] || config.providers.default;
+
+  const soundName = (p.sound && (p.sound[event] || p.sound.done)) || null;
+  const template = (event === 'waiting' ? config.waitingMessage : config.doneMessage) || '';
+  const fromTemplate = template.replace(/\{label\}/g, label).replace(/\s+/g, ' ').trim();
+  const fallback = event === 'waiting' ? 'is waiting for input' : 'finished';
+  // The agent's own text (Codex's reply, a Claude prompt) is in the agent's
+  // language — often English — not necessarily the user's. Three modes:
+  //   speakAgentMessage:false  -> never speak it; use the localized template.
+  //   translateTo set          -> translate it into your language, speak that
+  //                               (falling back to the template on failure).
+  //   default                  -> speak the raw message as-is.
+  // The desktop banner always shows the full original message visually.
+  let speakText;
+  if (config.speakAgentMessage === false) {
+    speakText = fromTemplate || fallback;
+  } else if (message) {
+    if (config.translateTo) {
+      const translated = translate(message, config.translateTo);
+      speakText = translated || fromTemplate || fallback;
+    } else {
+      speakText = message;
+    }
+  } else {
+    speakText = fromTemplate || fallback;
+  }
+
+  // Voice precedence (most specific first):
+  //   $AI_NOTIFY_VOICE  — set per terminal window/pane to give each its own voice
+  //   provider voice    — per agent (Claude vs Codex)
+  //   global voice      — the single `ai-notify voice` switch
+  const voice = process.env.AI_NOTIFY_VOICE || p.voice || config.voice;
+
+  if (!muted) {
+    playSound(soundName);
+    if (config.speak) speak(speakText, voice);
+  }
+
+  if (!muted || config.bannerWhenMuted) {
+    const title = 'AI Notify';
+    banner(title, label || provider, message || speakText);
+  }
+};