@spencer-kit/agent-notify 0.1.0

package/README.md

@@ -0,0 +1,184 @@
+# agent-notify
+
+`agent-notify` is a native TypeScript CLI for sending local completion and attention notifications from Codex and Claude Code.
+
+Published package:
+
+- `@spencer-kit/agent-notify`
+- installed executable: `agent-notify`
+
+## What It Does
+
+- patches Codex and Claude Code config files to call `agent-notify` when work finishes or needs input
+- normalizes Codex and Claude hook payloads into a shared event model
+- sends local desktop notifications and sound fallbacks
+- dedupes repeated events and keeps a local event log
+
+## Install
+
+Global install:
+
+```bash
+npm install -g @spencer-kit/agent-notify
+```
+
+One-off execution:
+
+```bash
+npx @spencer-kit/agent-notify install codex --dry-run
+```
+
+After install, the command name is still:
+
+```bash
+agent-notify
+```
+
+## Quick Start
+
+Install the Codex hook:
+
+```bash
+agent-notify install codex
+```
+
+Install the Claude Code hooks:
+
+```bash
+agent-notify install claude
+```
+
+Preview the generated config before writing anything:
+
+```bash
+agent-notify install codex --dry-run
+agent-notify install claude --dry-run
+```
+
+## Commands
+
+Install the Codex hook into `~/.codex/config.toml`:
+
+```bash
+agent-notify install codex
+```
+
+Install the Claude Code hooks into `~/.claude/settings.json`:
+
+```bash
+agent-notify install claude
+```
+
+Preview either install without writing files:
+
+```bash
+agent-notify install codex --dry-run
+agent-notify install claude --dry-run
+```
+
+Handle a Codex notify payload directly:
+
+```bash
+agent-notify handle codex '{"type":"agent-turn-complete","thread-id":"thread-1","turn-id":"turn-1","cwd":"/tmp/demo","input-messages":["rename foo"],"last-assistant-message":"rename complete"}'
+```
+
+Handle a Claude Code hook payload from stdin:
+
+```bash
+printf '%s\n' '{"session_id":"session-1","cwd":"/tmp/demo","notification_type":"idle_prompt","message":"Claude is waiting"}' | agent-notify handle claude --event Notification
+```
+
+Supported Claude events:
+
+- `Notification`
+- `Stop`
+- `StopFailure`
+
+CLI forms:
+
+```bash
+agent-notify install codex [--config <path>] [--dry-run]
+agent-notify install claude [--settings <path>] [--dry-run]
+agent-notify handle codex '<json>' [--state-dir <path>]
+agent-notify handle claude --event <Notification|Stop|StopFailure> ['<json>'] [--state-dir <path>]
+```
+
+If the JSON payload is omitted for `handle`, the CLI reads it from stdin.
+
+## Paths
+
+- Codex config: `~/.codex/config.toml`
+- Claude settings: `~/.claude/settings.json`
+- global config: `~/.config/agent-notify/config.toml`
+- repo override: `.agent-notify.toml`
+- state dir: `~/.local/state/agent-notify`
+
+## Notification Behavior
+
+- `Notification` maps to `needs_input`
+- `Stop` maps to `completed`
+- `StopFailure` maps to `failed`
+- desktop delivery falls back across supported local mechanisms
+- repeated events are suppressed for a short dedupe window
+- provider failures are fail-open and should not block agent execution
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+npm pack
+```
+
+## Release
+
+This repository is set up for GitHub Actions based publishing to npm when a GitHub Release is published from a version tag.
+
+### One-Time Setup
+
+1. Create the GitHub repository at `spencerkit/agent-notify`, or update `package.json` if your actual repo slug differs.
+2. On npm, configure `@spencer-kit/agent-notify` to use a GitHub Actions Trusted Publisher.
+3. In the npm Trusted Publisher configuration, use this repository and this exact workflow filename:
+
+```text
+release.yml
+```
+
+The workflow filename must match exactly or npm trusted publishing will reject the release job.
+
+If this is the very first publish and the package does not exist on npm yet, do one manual bootstrap publish first:
+
+```bash
+npm publish --access public
+```
+
+After the package exists, configure the Trusted Publisher in the package settings and use the GitHub Release flow below for subsequent releases.
+
+### Release Steps
+
+1. Update `package.json` to the target version.
+2. Run the local verification steps:
+
+```bash
+npm test
+npm run build
+npm pack --dry-run
+```
+
+3. Commit the release changes.
+4. Create and push the version tag:
+
+```bash
+git tag v0.1.0
+git push origin main --tags
+```
+
+5. In GitHub, create a GitHub Release from that tag and publish it.
+6. GitHub Actions runs [`release.yml`](./.github/workflows/release.yml), verifies the tag matches `package.json`, reruns CI, and publishes the package to npm.
+
+### GitHub Actions
+
+- [`ci.yml`](./.github/workflows/ci.yml) runs on pushes to `main` and on pull requests.
+- [`release.yml`](./.github/workflows/release.yml) runs only when a GitHub Release is published.
+- The release workflow uses npm Trusted Publisher authentication and publishes the public scoped package with provenance.

package/dist/cli.js

@@ -0,0 +1,1023 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { realpathSync } from "fs";
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname2, join as join3 } from "path";
+import { fileURLToPath } from "url";
+
+// src/config.ts
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+var DEFAULT_CONFIG = {
+  desktopEnabled: true,
+  soundEnabled: true,
+  soundOnCompleted: true,
+  dedupeSeconds: 15,
+  maxLogEntries: 5e3,
+  maxLogAgeDays: 7,
+  summaryLength: 180
+};
+var FILE_KEY_MAP = {
+  desktop_enabled: "desktopEnabled",
+  sound_enabled: "soundEnabled",
+  sound_on_completed: "soundOnCompleted",
+  dedupe_seconds: "dedupeSeconds",
+  max_log_entries: "maxLogEntries",
+  max_log_age_days: "maxLogAgeDays",
+  summary_length: "summaryLength"
+};
+var ENV_KEY_MAP = {
+  AGENT_NOTIFY_DESKTOP_ENABLED: "desktopEnabled",
+  AGENT_NOTIFY_SOUND_ENABLED: "soundEnabled",
+  AGENT_NOTIFY_SOUND_ON_COMPLETED: "soundOnCompleted",
+  AGENT_NOTIFY_DEDUPE_SECONDS: "dedupeSeconds",
+  AGENT_NOTIFY_MAX_LOG_ENTRIES: "maxLogEntries",
+  AGENT_NOTIFY_MAX_LOG_AGE_DAYS: "maxLogAgeDays",
+  AGENT_NOTIFY_SUMMARY_LENGTH: "summaryLength"
+};
+function defaultStateDir() {
+  return process.env.XDG_STATE_HOME ? join(process.env.XDG_STATE_HOME, "agent-notify") : join(homedir(), ".local", "state", "agent-notify");
+}
+function defaultConfigPath() {
+  return process.env.XDG_CONFIG_HOME ? join(process.env.XDG_CONFIG_HOME, "agent-notify", "config.toml") : join(homedir(), ".config", "agent-notify", "config.toml");
+}
+function findRepoConfig(cwd) {
+  if (!cwd) {
+    return void 0;
+  }
+  let current = resolve(cwd);
+  while (true) {
+    const candidate = join(current, ".agent-notify.toml");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = resolve(current, "..");
+    if (parent === current) {
+      return void 0;
+    }
+    current = parent;
+  }
+}
+function loadConfig(cwd) {
+  const mergedRaw = {
+    ...readTomlConfig(defaultConfigPath()),
+    ...readTomlConfig(findRepoConfig(cwd)),
+    ...readEnvConfig()
+  };
+  return {
+    desktopEnabled: coerceBoolean(
+      mergedRaw.desktopEnabled,
+      DEFAULT_CONFIG.desktopEnabled
+    ),
+    soundEnabled: coerceBoolean(mergedRaw.soundEnabled, DEFAULT_CONFIG.soundEnabled),
+    soundOnCompleted: coerceBoolean(
+      mergedRaw.soundOnCompleted,
+      DEFAULT_CONFIG.soundOnCompleted
+    ),
+    dedupeSeconds: coerceInteger(
+      mergedRaw.dedupeSeconds,
+      DEFAULT_CONFIG.dedupeSeconds
+    ),
+    maxLogEntries: coerceInteger(
+      mergedRaw.maxLogEntries,
+      DEFAULT_CONFIG.maxLogEntries
+    ),
+    maxLogAgeDays: coerceInteger(
+      mergedRaw.maxLogAgeDays,
+      DEFAULT_CONFIG.maxLogAgeDays
+    ),
+    summaryLength: coerceInteger(
+      mergedRaw.summaryLength,
+      DEFAULT_CONFIG.summaryLength
+    )
+  };
+}
+function shouldPlaySound(config, state) {
+  if (!config.soundEnabled) {
+    return false;
+  }
+  if (state === "completed") {
+    return config.soundOnCompleted;
+  }
+  return state === "needs_input" || state === "failed";
+}
+function readTomlConfig(path) {
+  if (!path || !existsSync(path)) {
+    return {};
+  }
+  return parseFlatToml(readFileSync(path, "utf8"));
+}
+function parseFlatToml(source) {
+  const config = {};
+  for (const rawLine of source.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.length === 0 || line.startsWith("#")) {
+      continue;
+    }
+    const commentStart = line.indexOf("#");
+    const cleaned = commentStart >= 0 ? line.slice(0, commentStart).trim() : line;
+    const separatorIndex = cleaned.indexOf("=");
+    if (separatorIndex < 0) {
+      continue;
+    }
+    const rawKey = cleaned.slice(0, separatorIndex).trim();
+    const rawValue = cleaned.slice(separatorIndex + 1).trim();
+    const mappedKey = FILE_KEY_MAP[rawKey];
+    if (!mappedKey) {
+      continue;
+    }
+    assignRawConfigValue(config, mappedKey, rawValue);
+  }
+  return config;
+}
+function readEnvConfig() {
+  const config = {};
+  for (const [envKey, mappedKey] of Object.entries(ENV_KEY_MAP)) {
+    const rawValue = process.env[envKey];
+    if (rawValue === void 0) {
+      continue;
+    }
+    assignRawConfigValue(config, mappedKey, rawValue);
+  }
+  return config;
+}
+function coerceBoolean(value, fallback) {
+  const normalized = unquote(value ?? "").trim().toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["0", "false", "no", "off"].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+function coerceInteger(value, fallback) {
+  const normalized = unquote(value ?? "").trim();
+  if (!/^-?\d+$/.test(normalized)) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(normalized, 10);
+  return Number.isNaN(parsed) ? fallback : parsed;
+}
+function unquote(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function assignRawConfigValue(config, key, value) {
+  Object.assign(config, { [key]: value });
+}
+
+// src/events.ts
+function parseEvent(tool, rawEvent, eventName) {
+  if (tool === "codex") {
+    return parseCodexEvent(rawEvent);
+  }
+  return parseClaudeEvent(rawEvent, eventName);
+}
+function parseCodexEvent(rawEvent) {
+  if (rawEvent.type !== "agent-turn-complete") {
+    throw new Error("unsupported Codex payload");
+  }
+  const cwd = getString(rawEvent.cwd, ".");
+  return {
+    tool: "codex",
+    state: "completed",
+    sessionId: getString(
+      rawEvent["thread-id"],
+      getString(
+        rawEvent["thread_id"],
+        getString(
+          rawEvent["session_id"],
+          getString(rawEvent["turn-id"], getString(rawEvent["turn_id"], "unknown"))
+        )
+      )
+    ),
+    cwd,
+    project: projectFromCwd(cwd),
+    summary: normalizeSummary(
+      rawEvent["last-assistant-message"],
+      getString(rawEvent["last_assistant_message"], "Codex completed a turn")
+    ),
+    rawEvent,
+    occurredAt: toOccurredAt(rawEvent)
+  };
+}
+function parseClaudeEvent(rawEvent, eventName) {
+  const normalizedEventName = getString(eventName, getString(rawEvent.eventName, ""));
+  const notificationType = getString(
+    rawEvent.notification_type,
+    getString(rawEvent.notificationType, "")
+  );
+  const cwd = getString(rawEvent.cwd, ".");
+  const sessionId = getString(rawEvent.session_id, getString(rawEvent.sessionId, "unknown"));
+  if (normalizedEventName === "Notification" && ["permission_prompt", "idle_prompt", "elicitation_dialog"].includes(notificationType)) {
+    return {
+      tool: "claude",
+      state: "needs_input",
+      sessionId,
+      cwd,
+      project: projectFromCwd(cwd),
+      summary: normalizeSummary(
+        rawEvent.message,
+        `Claude notification: ${notificationType || "attention required"}`
+      ),
+      rawEvent,
+      occurredAt: toOccurredAt(rawEvent)
+    };
+  }
+  if (normalizedEventName === "Stop") {
+    return {
+      tool: "claude",
+      state: "completed",
+      sessionId,
+      cwd,
+      project: projectFromCwd(cwd),
+      summary: normalizeSummary(
+        rawEvent.last_assistant_message,
+        getString(rawEvent.message, "Claude completed a task")
+      ),
+      rawEvent,
+      occurredAt: toOccurredAt(rawEvent)
+    };
+  }
+  if (normalizedEventName === "StopFailure") {
+    const errorType = getString(rawEvent.error_type, getString(rawEvent.errorType, "unknown"));
+    return {
+      tool: "claude",
+      state: "failed",
+      sessionId,
+      cwd,
+      project: projectFromCwd(cwd),
+      summary: normalizeSummary(rawEvent.message, `Stop failure: ${errorType}`),
+      rawEvent,
+      occurredAt: toOccurredAt(rawEvent)
+    };
+  }
+  throw new Error(`unsupported Claude payload: ${normalizedEventName || "unknown"}`);
+}
+function getString(value, fallback) {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+function normalizeSummary(value, fallback) {
+  const candidate = typeof value === "string" ? value : fallback;
+  const normalized = candidate.trim().replace(/\s+/g, " ");
+  return normalized.length > 0 ? normalized : fallback;
+}
+function projectFromCwd(cwd) {
+  const parts = cwd.split("/").filter(Boolean);
+  return parts.at(-1) ?? cwd;
+}
+function toOccurredAt(rawEvent) {
+  const value = typeof rawEvent.occurredAt === "string" && rawEvent.occurredAt.length > 0 ? rawEvent.occurredAt : rawEvent.occurred_at;
+  return typeof value === "string" && value.length > 0 ? value : (/* @__PURE__ */ new Date()).toISOString();
+}
+
+// src/installers.ts
+function renderTomlArray(values) {
+  return `[${values.map((value) => JSON.stringify(value)).join(", ")}]`;
+}
+function firstTomlTableIndex(text) {
+  const match = text.match(/^[ \t]*\[/m);
+  return match?.index ?? -1;
+}
+function hasNonTopLevelAssignment(text, key) {
+  const searchLimit = firstTomlTableIndex(text);
+  if (searchLimit === -1) {
+    return false;
+  }
+  const tableText = text.slice(searchLimit);
+  const pattern = new RegExp(`^[ \\t]*${key}[ \\t]*=`, "m");
+  return pattern.test(tableText);
+}
+function findTopLevelAssignmentSpan(text, key) {
+  const searchLimit = firstTomlTableIndex(text);
+  const searchText = searchLimit === -1 ? text : text.slice(0, searchLimit);
+  const marker = key;
+  let start = searchText.indexOf(marker);
+  while (start !== -1) {
+    const lineStart = searchText.lastIndexOf("\n", start) + 1;
+    const prefix = searchText.slice(lineStart, start).trim();
+    if (prefix.length > 0) {
+      start = searchText.indexOf(marker, start + marker.length);
+      continue;
+    }
+    let cursor = start + marker.length;
+    while (cursor < searchText.length && /\s/.test(searchText[cursor])) {
+      cursor += 1;
+    }
+    if (cursor >= searchText.length || searchText[cursor] !== "=") {
+      start = searchText.indexOf(marker, start + marker.length);
+      continue;
+    }
+    cursor += 1;
+    while (cursor < searchText.length && /\s/.test(searchText[cursor])) {
+      cursor += 1;
+    }
+    if (cursor < searchText.length && searchText[cursor] === "[") {
+      let depth = 0;
+      let inDoubleQuotedString = false;
+      let inSingleQuotedString = false;
+      let inComment = false;
+      let escaped = false;
+      for (let index = cursor; index < searchText.length; index += 1) {
+        const char = searchText[index];
+        if (inComment) {
+          if (char === "\n") {
+            inComment = false;
+          }
+          continue;
+        }
+        if (inDoubleQuotedString) {
+          if (escaped) {
+            escaped = false;
+          } else if (char === "\\") {
+            escaped = true;
+          } else if (char === '"') {
+            inDoubleQuotedString = false;
+          }
+          continue;
+        }
+        if (inSingleQuotedString) {
+          if (char === "'") {
+            inSingleQuotedString = false;
+          }
+          continue;
+        }
+        if (char === '"') {
+          inDoubleQuotedString = true;
+          continue;
+        }
+        if (char === "'") {
+          inSingleQuotedString = true;
+          continue;
+        }
+        if (char === "#") {
+          inComment = true;
+          continue;
+        }
+        if (char === "[") {
+          depth += 1;
+          continue;
+        }
+        if (char === "]") {
+          depth -= 1;
+          if (depth === 0) {
+            let end2 = index + 1;
+            while (end2 < searchText.length && /[ \t]/.test(searchText[end2])) {
+              end2 += 1;
+            }
+            if (end2 < searchText.length && searchText[end2] === "#") {
+              while (end2 < searchText.length && searchText[end2] !== "\n") {
+                end2 += 1;
+              }
+            }
+            if (end2 < searchText.length && searchText[end2] === "\n") {
+              end2 += 1;
+            }
+            return [start, end2];
+          }
+        }
+      }
+      throw new TypeError(`Unterminated top-level ${key} array assignment in Codex config.`);
+    }
+    const lineEnd = searchText.indexOf("\n", cursor);
+    const end = lineEnd === -1 ? searchText.length : lineEnd + 1;
+    return [start, end];
+  }
+  return null;
+}
+function shellJoin(argv) {
+  return argv.map((part) => {
+    if (/^[A-Za-z0-9_./:-]+$/.test(part)) {
+      return part;
+    }
+    return `'${part.replace(/'/g, `'\\''`)}'`;
+  }).join(" ");
+}
+function buildCodexNotifyCommand(command = "agent-notify") {
+  return [command, "handle", "codex"];
+}
+function buildClaudeCommandPrefix(command = "agent-notify") {
+  return [command];
+}
+function patchCodexConfig(currentText, commandArgv) {
+  const replacement = `notify = ${renderTomlArray(commandArgv)}
+`;
+  if (hasNonTopLevelAssignment(currentText, "notify")) {
+    throw new TypeError("Found non-top-level notify assignment in Codex config.");
+  }
+  const existingSpan = findTopLevelAssignmentSpan(currentText, "notify");
+  if (existingSpan) {
+    const [start, end] = existingSpan;
+    return currentText.slice(0, start) + replacement + currentText.slice(end);
+  }
+  const tableIndex = firstTomlTableIndex(currentText);
+  if (tableIndex !== -1) {
+    const prefix = currentText.slice(0, tableIndex).replace(/\n+$/, "");
+    const suffix = currentText.slice(tableIndex).replace(/^\n+/, "");
+    const parts = [prefix, replacement.trimEnd(), suffix].filter((part) => part.length > 0);
+    return `${parts.join("\n\n").replace(/\n+$/, "")}
+`;
+  }
+  const base = currentText.replace(/\n+$/, "");
+  return base.length > 0 ? `${base}
+${replacement}` : replacement;
+}
+function patchClaudeSettings(currentText, commandPrefix) {
+  const normalizedCurrentText = currentText.trim().length > 0 ? currentText : "{}";
+  const parsed = JSON.parse(normalizedCurrentText);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new TypeError("Claude settings must be a JSON object.");
+  }
+  const hooksValue = parsed.hooks;
+  const hooks = hooksValue === void 0 ? {} : hooksValue && typeof hooksValue === "object" && !Array.isArray(hooksValue) ? hooksValue : null;
+  if (hooks === null) {
+    throw new TypeError("Claude settings hooks must be a JSON object when present.");
+  }
+  const commandFor = (eventName) => shellJoin([...commandPrefix, "handle", "claude", "--event", eventName]);
+  hooks.Notification = [
+    {
+      matcher: "permission_prompt|idle_prompt|elicitation_dialog",
+      hooks: [
+        {
+          type: "command",
+          command: commandFor("Notification")
+        }
+      ]
+    }
+  ];
+  hooks.Stop = [
+    {
+      hooks: [
+        {
+          type: "command",
+          command: commandFor("Stop")
+        }
+      ]
+    }
+  ];
+  hooks.StopFailure = [
+    {
+      hooks: [
+        {
+          type: "command",
+          command: commandFor("StopFailure")
+        }
+      ]
+    }
+  ];
+  parsed.hooks = hooks;
+  return `${JSON.stringify(parsed, null, 2)}
+`;
+}
+
+// src/providers.ts
+import { access } from "fs/promises";
+import { constants as fsConstants } from "fs";
+import { execFile } from "child_process";
+var DesktopProvider = class {
+  commandExists;
+  run;
+  constructor(options = {}) {
+    this.commandExists = options.commandExists ?? commandAvailable;
+    this.run = options.run ?? runCommand;
+  }
+  async send(event) {
+    const title = formatNotificationTitle(event);
+    if (await this.commandExists("osascript")) {
+      const sent = await this.execute([
+        "osascript",
+        "-e",
+        `display notification "${escapeAppleScriptString(event.summary)}" with title "${escapeAppleScriptString(title)}"`
+      ]);
+      if (sent) {
+        return true;
+      }
+    }
+    if (await this.commandExists("notify-send")) {
+      return this.execute(["notify-send", title, event.summary]);
+    }
+    return false;
+  }
+  async execute(command) {
+    try {
+      const result = await this.run(command);
+      return result.ok;
+    } catch {
+      return false;
+    }
+  }
+};
+var SoundProvider = class {
+  commandExists;
+  run;
+  writeTerminalBell;
+  writeStdoutBell;
+  constructor(options = {}) {
+    this.commandExists = options.commandExists ?? commandAvailable;
+    this.run = options.run ?? runCommand;
+    this.writeTerminalBell = options.writeTerminalBell ?? defaultWriteTerminalBell;
+    this.writeStdoutBell = options.writeStdoutBell ?? defaultWriteStdoutBell;
+  }
+  async send(_event) {
+    for (const command of SOUND_COMMANDS) {
+      if (!await this.commandExists(command.name)) {
+        continue;
+      }
+      try {
+        const result = await this.run(command.args);
+        if (result.ok) {
+          return true;
+        }
+      } catch {
+        continue;
+      }
+    }
+    try {
+      await this.writeTerminalBell();
+      return true;
+    } catch {
+      try {
+        await this.writeStdoutBell();
+        return true;
+      } catch {
+        return false;
+      }
+    }
+  }
+};
+var SOUND_COMMANDS = [
+  { name: "osascript", args: ["osascript", "-e", "beep 1"] },
+  { name: "paplay", args: ["paplay", "/usr/share/sounds/freedesktop/stereo/complete.oga"] },
+  { name: "aplay", args: ["aplay", "/usr/share/sounds/alsa/Front_Center.wav"] },
+  { name: "afplay", args: ["afplay", "/System/Library/Sounds/Glass.aiff"] }
+];
+function formatNotificationTitle(event) {
+  return `[${event.tool}] ${event.project} \xB7 ${event.state}`;
+}
+async function commandAvailable(command) {
+  const pathValue = process.env.PATH;
+  if (!pathValue) {
+    return false;
+  }
+  for (const directory of pathValue.split(":")) {
+    if (!directory) {
+      continue;
+    }
+    try {
+      await access(`${directory}/${command}`, fsConstants.X_OK);
+      return true;
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
+function runCommand(command) {
+  return new Promise((resolve2, reject) => {
+    execFile(command[0], command.slice(1), { timeout: 2e3 }, (error) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+      resolve2({ ok: true });
+    });
+  });
+}
+async function defaultWriteTerminalBell() {
+  const { open } = await import("fs/promises");
+  const handle = await open("/dev/tty", "w");
+  try {
+    await handle.writeFile("\x07", "utf8");
+  } finally {
+    await handle.close();
+  }
+}
+async function defaultWriteStdoutBell() {
+  process.stdout.write("\x07");
+}
+function escapeAppleScriptString(value) {
+  return value.replaceAll("\\", "\\\\").replaceAll('"', '\\"').replaceAll("\n", "\\n");
+}
+
+// src/notifier.ts
+var Notifier = class {
+  config;
+  store;
+  desktopProvider;
+  soundProvider;
+  constructor(options) {
+    this.config = options.config;
+    this.store = options.store;
+    this.desktopProvider = options.desktopProvider ?? new DesktopProvider();
+    this.soundProvider = options.soundProvider ?? new SoundProvider();
+  }
+  async notify(event) {
+    if (!await this.store.shouldEmit(event)) {
+      return {
+        emitted: false,
+        desktopSent: false,
+        soundSent: false
+      };
+    }
+    const desktopSent = this.config.desktopEnabled ? await safeSend(this.desktopProvider, event) : false;
+    const soundSent = shouldPlaySound(this.config, event.state) ? await safeSend(this.soundProvider, event) : false;
+    await this.store.record(event);
+    return {
+      emitted: true,
+      desktopSent,
+      soundSent
+    };
+  }
+};
+async function safeSend(provider, event) {
+  try {
+    return Boolean(await provider.send(event));
+  } catch {
+    return false;
+  }
+}
+
+// src/store.ts
+import { createHash } from "crypto";
+import { mkdir, readFile, rename, writeFile } from "fs/promises";
+import { dirname, join as join2 } from "path";
+var EventStore = class {
+  logPath;
+  dedupePath;
+  dedupeSeconds;
+  maxEntries;
+  maxAgeDays;
+  now;
+  constructor(stateDir, options) {
+    this.logPath = join2(stateDir, "events.jsonl");
+    this.dedupePath = join2(stateDir, "dedupe.json");
+    this.dedupeSeconds = options.dedupeSeconds;
+    this.maxEntries = options.maxEntries ?? 5e3;
+    this.maxAgeDays = options.maxAgeDays ?? 7;
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  async shouldEmit(event) {
+    const dedupe = this.pruneDedupe(await this.loadDedupe());
+    await this.writeDedupe(dedupe);
+    return !(this.eventKey(event) in dedupe);
+  }
+  async record(event) {
+    const dedupe = this.pruneDedupe(await this.loadDedupe());
+    dedupe[this.eventKey(event)] = this.now().toISOString();
+    await this.writeDedupe(dedupe);
+    const entries = await this.readLog();
+    entries.push(this.toRecord(event));
+    await this.writeLog(this.pruneLogEntries(entries));
+  }
+  async readLog() {
+    await this.ensureStateDir();
+    let content;
+    try {
+      content = await readFile(this.logPath, "utf8");
+    } catch (error) {
+      if (isMissingFileError(error)) {
+        return [];
+      }
+      throw error;
+    }
+    const entries = [];
+    for (const rawLine of content.split("\n")) {
+      const line = rawLine.trim();
+      if (!line) {
+        continue;
+      }
+      try {
+        const parsed = JSON.parse(line);
+        if (isEventRecord(parsed)) {
+          entries.push(parsed);
+        }
+      } catch (error) {
+        if (error instanceof SyntaxError) {
+          continue;
+        }
+        throw error;
+      }
+    }
+    return entries;
+  }
+  eventKey(event) {
+    const summaryHash = createHash("sha256").update(event.summary, "utf8").digest("hex");
+    return `${event.tool}|${event.sessionId}|${event.state}|${summaryHash}`;
+  }
+  async ensureStateDir() {
+    await mkdir(dirname(this.logPath), { recursive: true });
+  }
+  async loadDedupe() {
+    await this.ensureStateDir();
+    try {
+      const content = await readFile(this.dedupePath, "utf8");
+      return normalizeDedupeState(JSON.parse(content));
+    } catch (error) {
+      if (isMissingFileError(error) || error instanceof SyntaxError) {
+        return {};
+      }
+      throw error;
+    }
+  }
+  async writeDedupe(data) {
+    await this.ensureStateDir();
+    await this.atomicWriteFile(this.dedupePath, `${JSON.stringify(data, null, 2)}
+`);
+  }
+  pruneDedupe(data) {
+    const cutoff = this.now().getTime() - this.dedupeSeconds * 1e3;
+    const pruned = {};
+    for (const [key, timestamp] of Object.entries(data)) {
+      const value = Date.parse(timestamp);
+      if (Number.isNaN(value)) {
+        continue;
+      }
+      if (value >= cutoff) {
+        pruned[key] = new Date(value).toISOString();
+      }
+    }
+    return pruned;
+  }
+  pruneLogEntries(entries) {
+    const cutoff = this.now().getTime() - this.maxAgeDays * 24 * 60 * 60 * 1e3;
+    const kept = entries.filter((entry) => {
+      const occurredAt = Date.parse(entry.occurred_at);
+      return !Number.isNaN(occurredAt) && occurredAt >= cutoff;
+    });
+    return kept.slice(-this.maxEntries);
+  }
+  async writeLog(entries) {
+    await this.ensureStateDir();
+    const content = entries.map((entry) => JSON.stringify(entry)).join("\n") + (entries.length > 0 ? "\n" : "");
+    await this.atomicWriteFile(this.logPath, content);
+  }
+  toRecord(event) {
+    return {
+      tool: event.tool,
+      state: event.state,
+      session_id: event.sessionId,
+      cwd: event.cwd,
+      project: event.project,
+      summary: event.summary,
+      occurred_at: event.occurredAt,
+      raw_event: event.rawEvent
+    };
+  }
+  async atomicWriteFile(path, content) {
+    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tempPath, content, "utf8");
+    await rename(tempPath, path);
+  }
+};
+function isMissingFileError(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function normalizeDedupeState(value) {
+  if (!isPlainObject(value)) {
+    return {};
+  }
+  const normalized = {};
+  for (const [key, timestamp] of Object.entries(value)) {
+    if (typeof timestamp === "string") {
+      normalized[key] = timestamp;
+    }
+  }
+  return normalized;
+}
+function isEventRecord(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  return isString(value.tool) && isString(value.state) && isString(value.session_id) && isString(value.cwd) && isString(value.project) && isString(value.summary) && isString(value.occurred_at) && isPlainObject(value.raw_event);
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+  return typeof value === "string";
+}
+
+// src/cli.ts
+var DEFAULT_CODEX_CONFIG_PATH = join3(homedir2(), ".codex", "config.toml");
+var DEFAULT_CLAUDE_SETTINGS_PATH = join3(homedir2(), ".claude", "settings.json");
+async function main(argv = process.argv.slice(2), dependencies = {}) {
+  const io = createRuntime(dependencies);
+  if (process.env.AGENT_NOTIFY_SMOKE_SIGNAL === "1" && argv.length === 0) {
+    io.stdout.write("agent-notify:main-ran\n");
+  }
+  if (argv.length === 0) {
+    return 0;
+  }
+  try {
+    const [command, ...rest] = argv;
+    if (command === "handle") {
+      return await handleCommand(rest, io);
+    }
+    if (command === "install") {
+      return await installCommand(rest, io);
+    }
+    throw new Error(`unknown command: ${command}`);
+  } catch (error) {
+    io.stderr.write(`${toMessage(error)}
+`);
+    return 1;
+  }
+}
+async function handleCommand(argv, runtime) {
+  const source = argv[0];
+  if (source !== "codex" && source !== "claude") {
+    throw new Error("usage: agent-notify handle <codex|claude> ...");
+  }
+  const options = parseHandleOptions(source, argv.slice(1));
+  const payloadText = (await readPayloadText(options.payload, runtime.stdin)).trim();
+  if (!payloadText) {
+    throw new Error("missing JSON payload");
+  }
+  const payloadData = parseJsonObject(payloadText);
+  const event = parseEvent(source, payloadData, options.eventName);
+  const stateDir = options.stateDir ?? defaultStateDir();
+  const notifier = runtime.createNotifier?.(source, event.cwd, stateDir) ?? new Notifier({
+    config: loadConfig(event.cwd),
+    store: runtime.createStore?.(stateDir, event.cwd) ?? new EventStore(stateDir, configToStoreOptions(loadConfig(event.cwd)))
+  });
+  await notifier.notify(event);
+  return 0;
+}
+function isDirectExecution() {
+  const entryArg = process.argv[1];
+  if (!entryArg) {
+    return false;
+  }
+  try {
+    return realpathSync(entryArg) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+async function installCommand(argv, runtime) {
+  const target = argv[0];
+  if (target !== "codex" && target !== "claude") {
+    throw new Error("usage: agent-notify install <codex|claude> ...");
+  }
+  const options = parseInstallOptions(target, argv.slice(1));
+  const path = target === "codex" ? options.path ?? DEFAULT_CODEX_CONFIG_PATH : options.path ?? DEFAULT_CLAUDE_SETTINGS_PATH;
+  const currentText = await readExistingText(path, runtime.readFile);
+  const updatedText = target === "codex" ? patchCodexConfig(currentText, buildCodexNotifyCommand("agent-notify")) : patchClaudeSettings(currentText, buildClaudeCommandPrefix("agent-notify"));
+  if (options.dryRun) {
+    runtime.stdout.write(updatedText);
+    return 0;
+  }
+  await runtime.mkdir(dirname2(path));
+  await runtime.writeFile(path, updatedText, "utf8");
+  runtime.stdout.write(updatedText);
+  return 0;
+}
+function parseHandleOptions(source, argv) {
+  let eventName;
+  let payload;
+  let stateDir;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--event") {
+      eventName = requireValue(arg, argv[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (arg === "--state-dir") {
+      stateDir = requireValue(arg, argv[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      throw new Error(`unknown option: ${arg}`);
+    }
+    if (payload !== void 0) {
+      throw new Error("unexpected extra argument");
+    }
+    payload = arg;
+  }
+  if (source === "claude" && !eventName) {
+    throw new Error("missing required option: --event");
+  }
+  return { eventName, payload, stateDir };
+}
+function parseInstallOptions(target, argv) {
+  let dryRun = false;
+  let path;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (target === "codex" && arg === "--config") {
+      path = requireValue(arg, argv[index + 1]);
+      index += 1;
+      continue;
+    }
+    if (target === "claude" && arg === "--settings") {
+      path = requireValue(arg, argv[index + 1]);
+      index += 1;
+      continue;
+    }
+    throw new Error(`unknown option: ${arg}`);
+  }
+  return { dryRun, path };
+}
+function requireValue(flag, value) {
+  if (!value) {
+    throw new Error(`missing value for ${flag}`);
+  }
+  return value;
+}
+async function readPayloadText(explicitPayload, stdin) {
+  if (explicitPayload !== void 0) {
+    return explicitPayload;
+  }
+  return await stdin.read() ?? "";
+}
+async function readExistingText(path, readText) {
+  try {
+    return await readText(path, "utf8");
+  } catch (error) {
+    if (isMissingFileError2(error)) {
+      return "";
+    }
+    throw error;
+  }
+}
+function parseJsonObject(payloadText) {
+  const parsed = JSON.parse(payloadText);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("JSON payload must be an object");
+  }
+  return parsed;
+}
+function configToStoreOptions(config) {
+  return {
+    dedupeSeconds: config.dedupeSeconds,
+    maxEntries: config.maxLogEntries,
+    maxAgeDays: config.maxLogAgeDays
+  };
+}
+function createRuntime(dependencies) {
+  return {
+    stdin: dependencies.stdin ?? {
+      read: async () => {
+        let payload = "";
+        process.stdin.setEncoding("utf8");
+        for await (const chunk of process.stdin) {
+          payload += typeof chunk === "string" ? chunk : String(chunk);
+        }
+        return payload;
+      }
+    },
+    stdout: dependencies.stdout ?? process.stdout,
+    stderr: dependencies.stderr ?? process.stderr,
+    readFile: dependencies.readFile ?? readFile2,
+    writeFile: dependencies.writeFile ?? writeFile2,
+    mkdir: dependencies.mkdir ?? (async (path) => {
+      await mkdir2(path, { recursive: true });
+    }),
+    createStore: dependencies.createStore ?? ((stateDir, cwd) => {
+      const config = loadConfig(cwd);
+      return new EventStore(stateDir, configToStoreOptions(config));
+    }),
+    createNotifier: dependencies.createNotifier ?? ((tool, cwd, stateDir) => {
+      const config = loadConfig(cwd);
+      const store = dependencies.createStore?.(stateDir, cwd) ?? new EventStore(stateDir, configToStoreOptions(config));
+      return new Notifier({
+        config,
+        store
+      });
+    })
+  };
+}
+function isMissingFileError2(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function toMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+if (isDirectExecution()) {
+  void main().then(
+    (exitCode) => {
+      process.exitCode = exitCode;
+    },
+    (error) => {
+      process.stderr.write(`${toMessage(error)}
+`);
+      process.exitCode = 1;
+    }
+  );
+}
+export {
+  main
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@spencer-kit/agent-notify",
+  "version": "0.1.0",
+  "description": "CLI notifications for Codex and Claude Code task completion and attention events",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/spencerkit/agent-notify#readme",
+  "bugs": {
+    "url": "https://github.com/spencerkit/agent-notify/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spencerkit/agent-notify.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "bin": {
+    "agent-notify": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup src/cli.ts --format esm --out-dir dist --clean",
+    "prepack": "npm run build",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.2",
+    "vitest": "^3.1.1"
+  }
+}