ai-notify 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 unoryota
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,83 @@
+# ai-notify
+
+**Know the moment your terminal AI agent needs you** — a sound, a spoken read-out, and a desktop banner the instant Claude Code, Codex, or another agent finishes a turn or asks for input. One mute switch covers **all of them, across every terminal**. No daemon, no background process.
+
+Long-running agents leave you staring at a quiet terminal. `ai-notify` wires a tiny notification hook into each agent CLI you have installed, so you can look away and get pulled back exactly when there's something to do. And when you're in a meeting, **one tap silences every agent at once** — because they all read the same shared switch.
+
+```sh
+npm i -g ai-notify
+ai-notify init        # auto-detects your agents and wires them
+```
+
+## Why
+
+- **Get notified even if you never set it up.** The point is to *add* notifications. Muting is just a bonus feature on top.
+- **All your agents, one switch.** Use only Claude Code? Only Codex? Both? Plus others? Same experience. The mute flag is shared, so flipping it once is global.
+- **Zero friction.** No daemon. Re-run `init` anytime — it only wires what's newly detected and never clobbers your existing config.
+
+## Supported agents
+
+| Agent | Status | How it's wired |
+| ----- | ------ | -------------- |
+| Claude Code | ✅ | `Notification` + `Stop` hooks in `~/.claude/settings.json` |
+| Codex CLI | ✅ | `notify` in `~/.codex/config.toml` (`agent-turn-complete`) |
+| Gemini CLI | 🧪 detected, hook WIP | see [CONTRIBUTING](CONTRIBUTING.md) — PRs welcome |
+
+Adding another agent (aider, opencode, amp, ...) is a small PR: drop a file in `src/providers/`. See [CONTRIBUTING](CONTRIBUTING.md).
+
+## Usage
+
+```sh
+ai-notify init [--dry-run] [--only claude,codex]   # wire detected agents
+ai-notify uninstall [--only ...]                   # cleanly remove wiring
+ai-notify toggle | on | off | status              # the mute switch
+ai-notify doctor                                   # check deps & wiring
+ai-notify config [init]                            # print / write config
+```
+
+> After `init`, restart any already-running Codex session so it re-reads its config.
+
+## Mute everything — without touching a busy terminal
+
+You can't type a command into the terminal that's running an agent, and you want
+the current state visible at a glance. So don't drive this from a prompt — drive
+it from the **menu bar / a hotkey**, and show the state where you can always see it.
+
+> Toggling works mid-run: the flag is read the next time an agent fires a
+> notification, so flipping it instantly affects every running agent. A hotkey
+> runs in its own process — it never types into your busy terminal.
+
+**Recommended — always-visible menu bar toggle** (pick one):
+
+- **Hammerspoon** — menu bar icon **and** a global hotkey (⌃⌥M) in ~20 lines. [recipes/hammerspoon](recipes/hammerspoon/).
+- **SwiftBar / xbar** — a 🔔/🔕 menu bar item you click to toggle. [recipes/swiftbar](recipes/swiftbar/).
+- **macOS Shortcuts** — `ai-notify toggle` pinned to the menu bar / a hotkey / iPhone. [recipes/macos-shortcut](recipes/macos-shortcut/).
+- **Raycast** — drop-in script command + hotkey. [recipes/raycast](recipes/raycast/).
+
+**Always-visible state** — `ai-notify status --icon` prints just `🔔`/`🔕`, ready to embed:
+
+- **Inside Claude Code's own status line** (the busy terminal shows its own state). [recipes/claude-statusline](recipes/claude-statusline/).
+- **tmux status bar / shell prompt / Starship.** [recipes/tmux](recipes/tmux/).
+
+## How it works
+
+`ai-notify` keeps a single mute flag and config under XDG paths:
+
+```
+${XDG_STATE_HOME:-~/.local/state}/ai-notify/muted     # presence = muted
+${XDG_CONFIG_HOME:-~/.config}/ai-notify/config.json   # sounds, voice, options
+```
+
+Each agent's hook calls `ai-notify hook --source <agent>`, which reads that one flag at fire time. That's why every agent and every terminal stay in sync with no coordination.
+
+### Configuration
+
+`ai-notify config init` writes a config you can edit — per-agent sounds and voice, whether the desktop banner still shows while muted, and whether to speak a read-out. Sounds default to OS built-ins, so nothing is bundled.
+
+## Platforms
+
+macOS is fully supported (`afplay` / `say` / `terminal-notifier` or `osascript`). Linux is best-effort (`paplay`/`canberra`, `notify-send`, `spd-say`/`espeak`). Windows plays a beep and speaks via PowerShell. Missing backends degrade silently — they never error.
+
+## License
+
+[MIT](LICENSE).

package/menubar/AiNotifyMenuBar.swift

@@ -0,0 +1,122 @@
+// ai-notify menu bar agent — a tiny native NSStatusItem that mirrors the one
+// shared mute flag and toggles it on click. No third-party app required.
+//
+// Single source of truth: the same file the CLI and every wired agent read,
+//   ${XDG_STATE_HOME:-~/.local/state}/ai-notify/muted
+// Present = muted (🔕). Absent = on (🔔).
+//
+// Left click  : toggle mute/unmute (one tap)
+// Right click : menu (toggle / quit)
+//
+// Builds with the system `swiftc` — no Xcode project, no dependencies.
+
+import Cocoa
+
+// MARK: - Shared state (must match src/state.mjs)
+
+enum State {
+    static func stateDir() -> String {
+        let env = ProcessInfo.processInfo.environment
+        let base = env["XDG_STATE_HOME"]
+            ?? (NSHomeDirectory() as NSString).appendingPathComponent(".local/state")
+        return (base as NSString).appendingPathComponent("ai-notify")
+    }
+
+    static func flagPath() -> String {
+        (stateDir() as NSString).appendingPathComponent("muted")
+    }
+
+    static var isMuted: Bool {
+        FileManager.default.fileExists(atPath: flagPath())
+    }
+
+    static func setMuted(_ muted: Bool) {
+        let path = flagPath()
+        let fm = FileManager.default
+        if muted {
+            try? fm.createDirectory(atPath: stateDir(), withIntermediateDirectories: true)
+            fm.createFile(atPath: path, contents: Data())
+        } else {
+            try? fm.removeItem(atPath: path)
+        }
+    }
+}
+
+// MARK: - App
+
+final class AppDelegate: NSObject, NSApplicationDelegate {
+    private var statusItem: NSStatusItem!
+    private var timer: Timer?
+
+    func applicationDidFinishLaunching(_ notification: Notification) {
+        statusItem = NSStatusBar.system.statusItem(withLength: NSStatusItem.variableLength)
+        if let button = statusItem.button {
+            button.action = #selector(handleClick(_:))
+            button.target = self
+            button.sendAction(on: [.leftMouseUp, .rightMouseUp])
+        }
+        render()
+        // Reconcile every second so external changes (CLI `ai-notify on/off`,
+        // another tool) are reflected without any IPC.
+        timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in
+            self?.render()
+        }
+    }
+
+    private func render() {
+        statusItem.button?.title = State.isMuted ? "🔕" : "🔔"
+    }
+
+    @objc private func handleClick(_ sender: Any?) {
+        guard let event = NSApp.currentEvent else { toggle(); return }
+        if event.type == .rightMouseUp {
+            showMenu()
+        } else {
+            toggle()
+        }
+    }
+
+    private func toggle() {
+        let nowMuted = !State.isMuted
+        State.setMuted(nowMuted)
+        render()
+        if !nowMuted { chime() } // brief confirmation on un-mute
+    }
+
+    @objc private func toggleFromMenu() { toggle() }
+
+    @objc private func quit() { NSApp.terminate(nil) }
+
+    private func showMenu() {
+        let muted = State.isMuted
+        let menu = NSMenu()
+        let toggleItem = NSMenuItem(
+            title: muted ? "通知をオンにする" : "ミュート",
+            action: #selector(toggleFromMenu), keyEquivalent: "")
+        toggleItem.target = self
+        menu.addItem(toggleItem)
+        menu.addItem(.separator())
+        let quitItem = NSMenuItem(title: "ai-notify を終了", action: #selector(quit), keyEquivalent: "q")
+        quitItem.target = self
+        menu.addItem(quitItem)
+
+        statusItem.menu = menu
+        statusItem.button?.performClick(nil)
+        statusItem.menu = nil // restore left-click-to-toggle
+    }
+
+    private func chime() {
+        let sound = "/System/Library/Sounds/Glass.aiff"
+        guard FileManager.default.fileExists(atPath: sound) else { return }
+        let task = Process()
+        task.executableURL = URL(fileURLWithPath: "/usr/bin/afplay")
+        task.arguments = ["-v", "2", sound]
+        try? task.run()
+    }
+}
+
+let app = NSApplication.shared
+app.setActivationPolicy(.accessory) // no Dock icon, menu bar only
+let delegate = AppDelegate()
+app.delegate = delegate
+app.run()

package/menubar/README.md

@@ -0,0 +1,58 @@
+# ai-notify menu bar agent (macOS)
+
+A tiny native menu bar bell so the mute switch has a **live 🔔 / 🔕 you can
+click** — with **no third-party app** (no Hammerspoon, SwiftBar, Raycast).
+
+- `AiNotifyMenuBar.swift` — the whole agent (~120 lines, AppKit `NSStatusItem`).
+- `build.sh` — compiles it into `dist/ai-notify.app` with the system `swiftc`.
+  No Xcode project, no dependencies.
+
+It reads and writes the **same mute flag** the CLI uses
+(`${XDG_STATE_HOME:-~/.local/state}/ai-notify/muted`), so the icon, the CLI, and
+every wired agent always agree — no daemon, no IPC.
+
+- **Left click** — toggle mute / un-mute (one tap)
+- **Right click** — menu (toggle / quit)
+
+## Use it
+
+```sh
+ai-notify menubar install      # build if needed, run at login, show the bell
+ai-notify menubar status
+ai-notify menubar uninstall
+```
+
+`install` writes a per-user LaunchAgent
+(`~/Library/LaunchAgents/com.ai-notify.menubar.plist`, `LimitLoadToSessionType
+= Aqua`) so the bell returns automatically at every login.
+
+## Build manually
+
+```sh
+bash menubar/build.sh                                   # ad-hoc signed, local use
+CODESIGN_ID="Developer ID Application: NAME (TEAMID)" \
+  bash menubar/build.sh                                 # Developer ID signed
+```
+
+## Distribution (npm)
+
+The published tarball ships a **prebuilt** `dist/ai-notify.app`, so end users get
+the bell without needing the Swift toolchain. `prepack` builds it automatically
+on `npm publish` from a Mac.
+
+Gatekeeper note: files installed by npm are **not quarantined**, so the bundled
+app launches even without notarization. For a hardened release, sign with a
+Developer ID and notarize:
+
+```sh
+CODESIGN_ID="Developer ID Application: NAME (TEAMID)" bash menubar/build.sh
+ditto -c -k --keepParent menubar/dist/ai-notify.app /tmp/ai-notify.zip
+xcrun notarytool submit /tmp/ai-notify.zip \
+  --apple-id "you@example.com" --team-id TEAMID --password "APP_SPECIFIC_PW" --wait
+xcrun stapler staple menubar/dist/ai-notify.app
+```
+
+On non-macOS platforms the menu bar agent is unavailable; `status --icon`
+(🔔/🔕) still embeds into tmux / shell prompts / SwiftBar, and the recipes in
+`../recipes/` cover Hammerspoon, SwiftBar, Raycast, and the built-in Shortcuts
+app for anyone who prefers those.

package/menubar/build.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Build the ai-notify menu bar agent into a self-contained .app bundle using the
+# system Swift toolchain. No Xcode project, no dependencies.
+#
+#   menubar/build.sh                      -> menubar/dist/ai-notify.app  (unsigned)
+#   CODESIGN_ID="Developer ID Application: ..." menubar/build.sh   -> signed
+#
+# Notarization (release only) is a separate step, see menubar/README.md.
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SRC="$HERE/AiNotifyMenuBar.swift"
+APP="$HERE/dist/ai-notify.app"
+BIN_NAME="ai-notify-menubar"
+
+rm -rf "$APP"
+mkdir -p "$APP/Contents/MacOS" "$APP/Contents/Resources"
+
+# Universal binary when possible (arm64 + x86_64), so one bundle runs everywhere.
+ARCH_FLAGS=(-target arm64-apple-macos11)
+if swiftc -target x86_64-apple-macos11 -typecheck "$SRC" >/dev/null 2>&1; then
+  ARCH_FLAGS=(-target arm64-apple-macos11)
+fi
+
+echo "compiling $BIN_NAME ..."
+swiftc -O "${ARCH_FLAGS[@]}" -o "$APP/Contents/MacOS/$BIN_NAME" "$SRC"
+
+cat > "$APP/Contents/Info.plist" <<PLIST
+<?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>CFBundleName</key><string>ai-notify</string>
+  <key>CFBundleDisplayName</key><string>ai-notify</string>
+  <key>CFBundleIdentifier</key><string>com.ai-notify.menubar</string>
+  <key>CFBundleVersion</key><string>0.1.0</string>
+  <key>CFBundleShortVersionString</key><string>0.1.0</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleExecutable</key><string>$BIN_NAME</string>
+  <key>LSMinimumSystemVersion</key><string>11.0</string>
+  <key>LSUIElement</key><true/>
+  <key>NSHighResolutionCapable</key><true/>
+</dict>
+</plist>
+PLIST
+
+if [ -n "${CODESIGN_ID:-}" ]; then
+  echo "code signing with: $CODESIGN_ID"
+  codesign --force --options runtime --timestamp \
+    --sign "$CODESIGN_ID" "$APP"
+else
+  # Ad-hoc sign so locally-built bundles launch without a quarantine prompt loop.
+  codesign --force --sign - "$APP" 2>/dev/null || true
+fi
+
+echo "built: $APP"

package/menubar/dist/ai-notify.app/Contents/Info.plist

@@ -0,0 +1,16 @@
+<?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>CFBundleName</key><string>ai-notify</string>
+  <key>CFBundleDisplayName</key><string>ai-notify</string>
+  <key>CFBundleIdentifier</key><string>com.ai-notify.menubar</string>
+  <key>CFBundleVersion</key><string>0.1.0</string>
+  <key>CFBundleShortVersionString</key><string>0.1.0</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleExecutable</key><string>ai-notify-menubar</string>
+  <key>LSMinimumSystemVersion</key><string>11.0</string>
+  <key>LSUIElement</key><true/>
+  <key>NSHighResolutionCapable</key><true/>
+</dict>
+</plist>

package/menubar/dist/ai-notify.app/Contents/_CodeSignature/CodeResources

@@ -0,0 +1,115 @@
+<?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>files</key>
+	<dict/>
+	<key>files2</key>
+	<dict/>
+	<key>rules</key>
+	<dict>
+		<key>^Resources/</key>
+		<true/>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^version.plist$</key>
+		<true/>
+	</dict>
+	<key>rules2</key>
+	<dict>
+		<key>.*\.dSYM($|/)</key>
+		<dict>
+			<key>weight</key>
+			<real>11</real>
+		</dict>
+		<key>^(.*/)?\.DS_Store$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>2000</real>
+		</dict>
+		<key>^(Frameworks|SharedFrameworks|PlugIns|Plug-ins|XPCServices|Helpers|MacOS|Library/(Automator|Spotlight|LoginItems))/</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^.*</key>
+		<true/>
+		<key>^Info\.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^PkgInfo$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^Resources/.*\.lproj/</key>
+		<dict>
+			<key>optional</key>
+			<true/>
+			<key>weight</key>
+			<real>1000</real>
+		</dict>
+		<key>^Resources/.*\.lproj/locversion.plist$</key>
+		<dict>
+			<key>omit</key>
+			<true/>
+			<key>weight</key>
+			<real>1100</real>
+		</dict>
+		<key>^Resources/Base\.lproj/</key>
+		<dict>
+			<key>weight</key>
+			<real>1010</real>
+		</dict>
+		<key>^[^/]+$</key>
+		<dict>
+			<key>nested</key>
+			<true/>
+			<key>weight</key>
+			<real>10</real>
+		</dict>
+		<key>^embedded\.provisionprofile$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+		<key>^version\.plist$</key>
+		<dict>
+			<key>weight</key>
+			<real>20</real>
+		</dict>
+	</dict>
+</dict>
+</plist>

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "ai-notify",
+  "version": "0.1.0",
+  "description": "Desktop, sound, and spoken notifications for terminal AI coding agents (Claude Code, Codex, Gemini, ...) — with one mute switch that covers all of them, across every terminal.",
+  "type": "module",
+  "bin": {
+    "ai-notify": "src/cli.mjs"
+  },
+  "exports": "./src/cli.mjs",
+  "files": [
+    "src",
+    "recipes",
+    "menubar/AiNotifyMenuBar.swift",
+    "menubar/build.sh",
+    "menubar/README.md",
+    "menubar/dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "scrub": "node scripts/scrub.mjs",
+    "build:menubar": "bash menubar/build.sh",
+    "prepack": "bash menubar/build.sh 2>/dev/null || true"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "ai-agent",
+    "notifications",
+    "desktop-notification",
+    "hooks",
+    "cli",
+    "terminal",
+    "productivity"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "author": "unoryota",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unoryota/ai-notify.git"
+  },
+  "homepage": "https://github.com/unoryota/ai-notify#readme",
+  "bugs": {
+    "url": "https://github.com/unoryota/ai-notify/issues"
+  },
+  "dependencies": {}
+}

package/recipes/claude-statusline/README.md

@@ -0,0 +1,30 @@
+# Show mute state inside Claude Code's own status line
+
+The terminal running Claude Code is exactly the one you *can't* type into while
+it's working — but Claude Code can render a **status line** at the bottom. Put
+the mute indicator there, and the busy terminal shows `🔔` / `🔕` on its own.
+
+Add this to `~/.claude/settings.json` (merge with any existing `statusLine`):
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "ai-notify status --icon"
+  }
+}
+```
+
+Want more context in the line? Combine it with your own info:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "printf '%s  %s' \"$(ai-notify status --icon)\" \"$(basename \"$PWD\")\""
+  }
+}
+```
+
+> Note: Claude Code allows a single `statusLine`. If you already use one, fold
+> `ai-notify status --icon` into your existing command rather than replacing it.

package/recipes/hammerspoon/ai-notify.lua

@@ -0,0 +1,69 @@
+-- Menu bar indicator + global hotkey for ai-notify, via Hammerspoon.
+--
+-- Gives you BOTH at once, with no extra app beyond Hammerspoon (free):
+--   * an always-visible 🔔 / 🔕 in the menu bar (click to toggle)
+--   * a global hotkey (⌃⌥M) that toggles from anywhere — even while a terminal
+--     is busy running an agent, because the hotkey runs in its own process and
+--     never types into that terminal.
+--
+-- The toggle is INSTANT and RELIABLE: it writes the shared mute flag file
+-- directly (the same file ai-notify reads), so the icon always reflects the
+-- real state — it never gets ahead of a slow/failed subprocess.
+--
+-- Install:
+--   1. brew install --cask hammerspoon  (and launch it once)
+--   2. Append the contents of this file to ~/.hammerspoon/init.lua
+--   3. Reload Hammerspoon config.
+
+local function flagPath()
+  local base = os.getenv("XDG_STATE_HOME")
+  return (base and (base .. "/ai-notify/muted"))
+    or (os.getenv("HOME") .. "/.local/state/ai-notify/muted")
+end
+
+local function isMuted()
+  local f = io.open(flagPath(), "r")
+  if f then f:close() return true end
+  return false
+end
+
+-- Authoritative: write/remove the flag file directly. Instant, can't fail to a
+-- subprocess, and is the single source of truth ai-notify and its hooks read.
+local function setMuted(muted)
+  local p = flagPath()
+  if muted then
+    local f = io.open(p, "w")
+    if not f then
+      hs.fs.mkdir(p:match("(.*)/")) -- create the state dir if missing
+      f = io.open(p, "w")
+    end
+    if f then f:close() end
+  else
+    os.remove(p)
+  end
+end
+
+local menubar = hs.menubar.new()
+
+local function setIcon(muted)
+  if menubar then menubar:setTitle(muted and "🔕" or "🔔") end
+end
+
+local function render() setIcon(isMuted()) end
+
+local function toggle()
+  local newMuted = not isMuted()
+  setMuted(newMuted) -- flip the real state first
+  setIcon(newMuted)  -- icon always matches reality
+  if not newMuted then
+    -- brief confirmation chime on un-mute (async, best-effort)
+    hs.task.new("/usr/bin/afplay", nil, { "-v", "2", "/System/Library/Sounds/Glass.aiff" }):start()
+  end
+end
+
+if menubar then menubar:setClickCallback(toggle) end
+hs.hotkey.bind({ "ctrl", "alt" }, "M", toggle)
+
+-- Safety reconciler in case the flag is changed elsewhere (CLI, another tool).
+hs.timer.doEvery(2, render)
+render()

package/recipes/macos-shortcut/README.md

@@ -0,0 +1,23 @@
+# One-tap mute on macOS (Shortcuts.app)
+
+Make muting every agent a single click / keypress / phone tap.
+
+1. Open **Shortcuts.app** → **+** (new shortcut).
+2. Add the action **Run Shell Script**.
+   - Shell: `zsh`
+   - Pass input: **to stdin** (doesn't matter; we ignore it)
+   - Script:
+     ```sh
+     ai-notify toggle
+     ```
+     If `ai-notify` isn't on the GUI PATH, use the full path (find it with
+     `which ai-notify`), e.g. `/usr/local/bin/ai-notify toggle` or
+     `/opt/homebrew/bin/ai-notify toggle`.
+3. Rename it to **"AI Notify Toggle"**.
+4. In the shortcut's settings (ⓘ), enable any of:
+   - **Pin in Menu Bar** → toggle from the top of the screen.
+   - **Add Keyboard Shortcut** (e.g. ⌃⌥M) → works from any app.
+   - It also appears on iPhone / Apple Watch / Control Center under the same Apple ID.
+
+That's it — one tap silences (or un-silences) Claude Code, Codex, and every other
+wired agent at once, because they all share the same switch.

package/recipes/raycast/ai-notify-toggle.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Raycast Script Command: toggle ai-notify mute for all agents.
+# Drop this file into your Raycast script directory and assign a hotkey.
+#
+# @raycast.schemaVersion 1
+# @raycast.title Toggle AI Notify
+# @raycast.mode compact
+# @raycast.icon 🔔
+# @raycast.packageName ai-notify
+#
+# Optional metadata:
+# @raycast.description Mute/unmute notifications for all terminal AI agents at once
+
+export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:$PATH"
+ai-notify toggle