ai-notify 0.1.0

package/src/providers/claude.mjs

@@ -0,0 +1,92 @@
+// Provider: Claude Code (Anthropic).
+//
+// Wires two hooks in ~/.claude/settings.json:
+//   - Notification -> "waiting" (Claude is asking for input/permission)
+//   - Stop         -> "done"    (Claude finished its turn)
+// Existing hooks are preserved; we only add/remove our own entries.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { MARKER } from '../util.mjs';
+
+const settingsPath = () => join(homedir(), '.claude', 'settings.json');
+
+export const id = 'claude';
+export const displayName = 'Claude Code';
+
+export const detect = () => existsSync(join(homedir(), '.claude'));
+
+const load = () => {
+  try {
+    return JSON.parse(readFileSync(settingsPath(), 'utf8'));
+  } catch {
+    return {};
+  }
+};
+
+const save = (data) => {
+  const dir = join(homedir(), '.claude');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(settingsPath(), JSON.stringify(data, null, 2) + '\n');
+};
+
+const isOurs = (cmd) => typeof cmd === 'string' && cmd.includes(MARKER) && cmd.includes(' hook ');
+
+const entry = (node, cliPath, event) => ({
+  matcher: '',
+  hooks: [
+    {
+      type: 'command',
+      command: `${node} ${cliPath} hook --source claude --event ${event}`,
+      async: true,
+    },
+  ],
+});
+
+const EVENTS = { Notification: 'waiting', Stop: 'done' };
+
+export const status = () => {
+  if (!detect()) return { installed: false, wired: false };
+  const data = load();
+  const hooks = data.hooks || {};
+  const wired = Object.keys(EVENTS).every((k) =>
+    (hooks[k] || []).some((g) => (g.hooks || []).some((h) => isOurs(h.command)))
+  );
+  return { installed: true, wired };
+};
+
+export const wire = ({ node, cliPath, dryRun }) => {
+  const data = load();
+  data.hooks = data.hooks || {};
+  const changes = [];
+  for (const [event, kind] of Object.entries(EVENTS)) {
+    data.hooks[event] = data.hooks[event] || [];
+    const already = data.hooks[event].some((g) => (g.hooks || []).some((h) => isOurs(h.command)));
+    if (!already) {
+      if (!dryRun) data.hooks[event].push(entry(node, cliPath, kind));
+      changes.push(`${event} -> ${kind}`);
+    }
+  }
+  if (!dryRun && changes.length) save(data);
+  return { changed: changes.length > 0, detail: changes.length ? changes.join(', ') : 'already wired', file: settingsPath() };
+};
+
+export const unwire = ({ dryRun } = {}) => {
+  const data = load();
+  if (!data.hooks) return { changed: false, detail: 'nothing to remove' };
+  let removed = 0;
+  for (const event of Object.keys(EVENTS)) {
+    const groups = data.hooks[event];
+    if (!Array.isArray(groups)) continue;
+    for (const g of groups) {
+      const before = (g.hooks || []).length;
+      g.hooks = (g.hooks || []).filter((h) => !isOurs(h.command));
+      removed += before - g.hooks.length;
+    }
+    data.hooks[event] = groups.filter((g) => (g.hooks || []).length > 0);
+    if (data.hooks[event].length === 0) delete data.hooks[event];
+  }
+  if (!dryRun && removed) save(data);
+  return { changed: removed > 0, detail: removed ? `removed ${removed} hook(s)` : 'nothing to remove', file: settingsPath() };
+};

package/src/providers/codex.mjs

@@ -0,0 +1,86 @@
+// Provider: Codex CLI (OpenAI).
+//
+// Codex calls a `notify` program with a single JSON argument (event
+// `agent-turn-complete`). We set the root `notify` key in ~/.codex/config.toml.
+//
+// TOML constraint: root keys must appear before any [table]. We insert our line
+// just before the first table. We never clobber a user's pre-existing notify
+// program — if one exists that isn't ours, we warn and skip.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { MARKER } from '../util.mjs';
+
+const configPath = () => join(homedir(), '.codex', 'config.toml');
+
+export const id = 'codex';
+export const displayName = 'Codex CLI';
+
+export const detect = () => existsSync(join(homedir(), '.codex'));
+
+const read = () => {
+  try {
+    return readFileSync(configPath(), 'utf8');
+  } catch {
+    return '';
+  }
+};
+
+const ourLine = (node, cliPath) =>
+  `notify = ["${node}", "${cliPath}", "hook", "--source", "codex"]`;
+
+const COMMENT = '# ai-notify: desktop/sound notification on agent-turn-complete';
+
+const findNotify = (text) => text.match(/^notify\s*=.*$/m);
+
+export const status = () => {
+  if (!detect()) return { installed: false, wired: false };
+  const m = findNotify(read());
+  return { installed: true, wired: !!(m && m[0].includes(MARKER)) };
+};
+
+export const wire = ({ node, cliPath, dryRun }) => {
+  let text = read();
+  const existing = findNotify(text);
+
+  if (existing && !existing[0].includes(MARKER)) {
+    return {
+      changed: false,
+      skipped: true,
+      detail: 'a custom `notify` already exists in config.toml — not overwriting it',
+      file: configPath(),
+    };
+  }
+
+  const line = ourLine(node, cliPath);
+
+  if (existing) {
+    if (existing[0] === line) return { changed: false, detail: 'already wired', file: configPath() };
+    text = text.replace(/^notify\s*=.*$/m, line);
+  } else {
+    const block = `${COMMENT}\n${line}\n`;
+    const tableIdx = text.search(/^\s*\[/m); // first [table]
+    if (tableIdx === -1) {
+      text = (text ? text.replace(/\n*$/, '\n') : '') + block;
+    } else {
+      text = text.slice(0, tableIdx) + block + '\n' + text.slice(tableIdx);
+    }
+  }
+
+  if (!dryRun) writeFileSync(configPath(), text);
+  return { changed: true, detail: 'set `notify`', file: configPath() };
+};
+
+export const unwire = ({ dryRun } = {}) => {
+  let text = read();
+  const existing = findNotify(text);
+  if (!existing || !existing[0].includes(MARKER)) {
+    return { changed: false, detail: 'nothing to remove', file: configPath() };
+  }
+  text = text
+    .replace(new RegExp(`^${COMMENT.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n`, 'm'), '')
+    .replace(/^notify\s*=.*\n?/m, '');
+  if (!dryRun) writeFileSync(configPath(), text);
+  return { changed: true, detail: 'removed `notify`', file: configPath() };
+};

package/src/providers/gemini.mjs

@@ -0,0 +1,30 @@
+// Provider: Gemini CLI (Google) — contributor stub.
+//
+// Gemini CLI is detected here, but a stable "turn complete" hook/notify
+// mechanism is not yet wired. This file is the on-ramp for contributors: see
+// claude.mjs / codex.mjs for the shape, implement detect/wire/unwire, and open
+// a PR. Until then `wire()` is a no-op that explains the situation.
+//
+// The same applies to adding any other agent (aider, opencode, amp, ...):
+// drop a new file in src/providers/ exporting the same interface and register
+// it in src/providers/index.mjs.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+
+export const id = 'gemini';
+export const displayName = 'Gemini CLI';
+export const experimental = true;
+
+export const detect = () => existsSync(join(homedir(), '.gemini'));
+
+export const status = () => ({ installed: detect(), wired: false });
+
+export const wire = () => ({
+  changed: false,
+  skipped: true,
+  detail: 'detected, but no supported notification hook yet — contributions welcome',
+});
+
+export const unwire = () => ({ changed: false, detail: 'nothing to remove' });

package/src/providers/index.mjs

@@ -0,0 +1,10 @@
+// Provider registry. To add a new agent, implement a provider module with the
+// shape { id, displayName, detect, status, wire, unwire } and add it here.
+
+import * as claude from './claude.mjs';
+import * as codex from './codex.mjs';
+import * as gemini from './gemini.mjs';
+
+export const providers = [claude, codex, gemini];
+
+export const byId = (id) => providers.find((p) => p.id === id);

package/src/state.mjs

@@ -0,0 +1,102 @@
+// Shared state for ai-notify: the mute flag and user config.
+//
+// Everything lives under XDG paths so that ALL wired agents (Claude Code, Codex,
+// Gemini, ...) read the same single source of truth. Flip the flag once and every
+// agent in every terminal obeys it — no daemon, no per-terminal action.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  mkdirSync,
+  existsSync,
+  writeFileSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs';
+
+const APP = 'ai-notify';
+
+const xdg = (envVar, fallback) =>
+  join(process.env[envVar] || join(homedir(), fallback), APP);
+
+export const stateDir = () => xdg('XDG_STATE_HOME', '.local/state');
+export const configDir = () => xdg('XDG_CONFIG_HOME', '.config');
+
+const muteFlagPath = () => join(stateDir(), 'muted');
+const configPath = () => join(configDir(), 'config.json');
+
+const ensureDir = (dir) => {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+};
+
+// --- Mute flag -------------------------------------------------------------
+
+export const isMuted = () => existsSync(muteFlagPath());
+
+export const setMuted = (muted) => {
+  if (muted) {
+    ensureDir(stateDir());
+    writeFileSync(muteFlagPath(), '');
+  } else if (existsSync(muteFlagPath())) {
+    rmSync(muteFlagPath());
+  }
+  return muted;
+};
+
+export const toggleMuted = () => setMuted(!isMuted());
+
+// --- Config ----------------------------------------------------------------
+
+// Sounds default to OS built-ins so we ship no audio assets (clean repo, no
+// licensing). Users can override any of this in config.json.
+export const DEFAULT_CONFIG = {
+  // Keep the desktop banner even while muted, so you still notice when you
+  // come back to your desk during a meeting.
+  bannerWhenMuted: true,
+  // Spoken read-out of which terminal finished (helps tell tabs apart).
+  speak: true,
+  // Whether to speak the agent's own text (Codex's reply, a Claude prompt).
+  // That text is in the agent's language — set this false to keep every spoken
+  // read-out in your own language via doneMessage / waitingMessage instead.
+  speakAgentMessage: true,
+  // Optional: translate the agent's message into this language before speaking
+  // it (e.g. 'ja'). Empty = off. Key-less, no cost; makes a network request.
+  // Toggle with `ai-notify translate on ja` / `off`.
+  translateTo: '',
+  // Spoken confirmation when you un-mute. Override per language/voice — e.g. a
+  // Japanese TTS voice reads the English word more naturally in katakana.
+  onMessage: 'notifications on',
+  // Global TTS voice for the spoken read-out (macOS `say` voice name, e.g.
+  // 'Kyoko'). Empty = OS default voice. Switch it with `ai-notify voice`. A
+  // per-provider `voice` below, if set, overrides this for that agent.
+  voice: '',
+  // Spoken read-out templates for agent events. `{label}` is the working-dir
+  // name. Override per language (e.g. Japanese) in config.json. An agent that
+  // supplies its own message (Codex's last reply, a Claude prompt) wins over
+  // these.
+  doneMessage: '{label} finished',
+  waitingMessage: '{label} is waiting for input',
+  providers: {
+    claude: { sound: { waiting: 'Glass', done: 'Hero' }, voice: '' },
+    codex: { sound: { done: 'Submarine' }, voice: '' },
+    gemini: { sound: { done: 'Ping' }, voice: '' },
+    default: { sound: { waiting: 'Glass', done: 'Hero' }, voice: '' },
+  },
+};
+
+export const readConfig = () => {
+  try {
+    const raw = JSON.parse(readFileSync(configPath(), 'utf8'));
+    return { ...DEFAULT_CONFIG, ...raw, providers: { ...DEFAULT_CONFIG.providers, ...(raw.providers || {}) } };
+  } catch {
+    return DEFAULT_CONFIG;
+  }
+};
+
+export const writeConfig = (config) => {
+  ensureDir(configDir());
+  writeFileSync(configPath(), JSON.stringify(config, null, 2) + '\n');
+  return configPath();
+};
+
+export const paths = { muteFlagPath, configPath, stateDir, configDir };

package/src/translate.mjs

@@ -0,0 +1,46 @@
+// Optional translation of an agent's spoken message into the user's language.
+//
+// The popular key-less translation npm packages (google-translate-api-x,
+// @vitalets/google-translate-api, bing-translate-api, ...) all boil down to one
+// HTTP GET against a public, key-less translate endpoint plus a little array
+// parsing. Rather than take a dependency, we reimplement that in a few lines
+// with `curl` — keeping the package dependency-free, with no API key and no
+// cost. (It does make a network request; offline use falls back to templates.)
+//
+// Best-effort: any failure returns null and the caller falls back to a
+// localized template, so notifications never break or hang.
+
+import { execFileSync } from 'node:child_process';
+
+const ENDPOINT = 'https://translate.googleapis.com/translate_a/single';
+
+// Translate `text` into `to` (BCP-47-ish, e.g. 'ja'). Source auto-detected.
+export const translate = (text, to = 'ja', timeoutMs = 4000) => {
+  if (!text || !to) return null;
+  try {
+    const out = execFileSync(
+      'curl',
+      [
+        '-s',
+        '--max-time', String(Math.max(1, Math.ceil(timeoutMs / 1000))),
+        '-G', ENDPOINT,
+        '--data-urlencode', `q=${text}`,
+        '-d', 'client=gtx',
+        '-d', 'sl=auto',
+        '-d', `tl=${to}`,
+        '-d', 'dt=t',
+      ],
+      { timeout: timeoutMs + 1000, encoding: 'utf8', maxBuffer: 1 << 20, stdio: ['ignore', 'pipe', 'ignore'] }
+    );
+    const data = JSON.parse(out);
+    // Shape: [ [ [translatedChunk, originalChunk, ...], ... ], ..., srcLang ]
+    const segments = Array.isArray(data) && Array.isArray(data[0]) ? data[0] : [];
+    const result = segments
+      .map((s) => (s && typeof s[0] === 'string' ? s[0] : ''))
+      .join('')
+      .trim();
+    return result || null;
+  } catch {
+    return null;
+  }
+};

package/src/util.mjs

@@ -0,0 +1,41 @@
+// Small shared helpers (no third-party deps).
+
+import { execFileSync } from 'node:child_process';
+import { basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// A human label for the terminal/tab, in priority order:
+//   1. $AI_NOTIFY_LABEL  (set it per tab to name your work)
+//   2. git branch of the working dir
+//   3. the directory name
+export const deriveLabel = (cwd) => {
+  if (process.env.AI_NOTIFY_LABEL) return process.env.AI_NOTIFY_LABEL;
+  if (cwd) {
+    try {
+      const branch = execFileSync('git', ['-C', cwd, 'rev-parse', '--abbrev-ref', 'HEAD'], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+      })
+        .toString()
+        .trim();
+      if (branch && branch !== 'HEAD') return `${basename(cwd)}/${branch}`;
+    } catch {
+      /* not a git repo */
+    }
+    return basename(cwd);
+  }
+  return 'somewhere';
+};
+
+// Absolute path to this package's CLI, and the node that should run it.
+// These get embedded into each agent's hook config so the hooks work
+// regardless of the shell's PATH at fire time.
+export const cliInvocation = () => ({
+  node: process.execPath,
+  cliPath: fileURLToPath(new URL('./cli.mjs', import.meta.url)),
+});
+
+// Hooks need a persistent install. `npx` runs from an ephemeral cache that can
+// be garbage-collected, which would break the wiring later.
+export const isEphemeralInstall = (cliPath) => /[/\\]_npx[/\\]/.test(cliPath);
+
+export const MARKER = 'ai-notify'; // substring used to detect our own wiring

package/src/voices.mjs

@@ -0,0 +1,69 @@
+// Voice discovery & preview for the spoken read-out.
+//
+// macOS only: we shell out to the built-in `say` command, which ships a large
+// set of offline system voices. No network, no API, no cost — switching voices
+// is free. On other platforms this returns an empty list and the `voice`
+// command degrades to "set any name you like by hand".
+
+import { execFileSync } from 'node:child_process';
+
+const isMac = process.platform === 'darwin';
+
+// Curated, ordered shortlist of distinct, good-quality built-in voices. We only
+// show the ones actually installed, then pad up to `limit` from the rest so the
+// menu is always ~10 even on a trimmed-down system.
+const PRESET = [
+  'Kyoko', 'Eddy', 'Flo', 'Reed', 'Rocko', 'Sandy', 'Shelley',
+  'Grandpa', 'Grandma', 'Otoya', 'Samantha', 'Alex', 'Daniel', 'Karen',
+];
+
+// Unique base voice names installed on this machine. Multilingual voices are
+// listed once per language by `say -v ?` (e.g. "Eddy (日本語（日本）)"); we strip
+// the "(language)" suffix and de-duplicate, since `say -v Eddy` works directly.
+export const installedVoiceNames = () => {
+  if (!isMac) return [];
+  let out = '';
+  try {
+    out = execFileSync('say', ['-v', '?'], { encoding: 'utf8' });
+  } catch {
+    return [];
+  }
+  const names = [];
+  for (const line of out.split('\n')) {
+    const m = line.match(/^(.+?)\s{2,}/); // name column = text before 2+ spaces
+    if (!m) continue;
+    const name = m[1].replace(/\s*\(.*\)\s*$/, '').trim(); // drop "(language)" suffix
+    if (name && !names.includes(name)) names.push(name);
+  }
+  return names;
+};
+
+// The ~10 options shown by `ai-notify voice`.
+export const curatedVoices = (limit = 10) => {
+  const installed = installedVoiceNames();
+  const have = new Set(installed);
+  const picked = PRESET.filter((n) => have.has(n));
+  for (const n of installed) {
+    if (picked.length >= limit) break;
+    if (!picked.includes(n)) picked.push(n);
+  }
+  return picked.slice(0, limit);
+};
+
+// Resolve a user argument (1-based number, or a name) to an installed voice.
+export const resolveVoice = (arg, list) => {
+  if (!arg) return null;
+  if (/^\d+$/.test(arg)) return list[Number(arg) - 1] || null;
+  const all = installedVoiceNames();
+  return all.find((n) => n.toLowerCase() === String(arg).toLowerCase()) || null;
+};
+
+// Speak a sample synchronously so previews play one after another, in order.
+export const previewVoice = (name, text) => {
+  if (!isMac || !name || !text) return;
+  try {
+    execFileSync('say', ['-v', name, text], { stdio: 'ignore' });
+  } catch {
+    /* voice missing / say unavailable — ignore */
+  }
+};