ai-notify 0.4.2 → 0.4.4

package/README.ja.md

@@ -2,6 +2,12 @@
 
 [English](README.md) · **日本語**
 
+[![npm](https://img.shields.io/npm/v/ai-notify?color=cb3837&logo=npm)](https://www.npmjs.com/package/ai-notify)
+[![downloads](https://img.shields.io/npm/dw/ai-notify?color=cb3837)](https://www.npmjs.com/package/ai-notify)
+[![license](https://img.shields.io/npm/l/ai-notify?color=blue)](./LICENSE)
+![platform](https://img.shields.io/badge/macOS%20%C2%B7%20Linux-zero--dep-success)
+[![stars](https://img.shields.io/github/stars/unoryota/ai-notify?style=social)](https://github.com/unoryota/ai-notify)
+
 **ターミナルのAIエージェントが「あなたを必要とした瞬間」を逃さない** — Claude Code・Codex などのエージェントがターンを終えた／入力を求めた瞬間に、音・読み上げ・デスクトップ通知で知らせます。**全エージェント・全ターミナルを1つのスイッチで一括ミュート**。デーモンも常駐プロセスも無し。
 
 ![ai-notify demo](https://raw.githubusercontent.com/unoryota/ai-notify/main/assets/hero-ja.gif)
@@ -13,6 +19,10 @@ brew install unoryota/tap/ai-notify   # macOS（Homebrew）
 ai-notify init        # インストール済みのエージェントを自動検出して配線
 ```
 
+セットアップはこれだけ。`init` が Claude Code / Codex / Gemini を見つけてフックを配線します。あとは1つのスイッチで全部を操作できます：
+
+![ai-notify の使い方: init・status・一括ミュート・声の切替](https://raw.githubusercontent.com/unoryota/ai-notify/main/assets/usage.gif)
+
 ## 何が違うか
 
 エージェントは数分間も沈黙しがち。ai-notify は適切な瞬間に呼び戻します。とくに **AIを並列でたくさん動かす運用**のために作られています：
@@ -23,6 +33,10 @@ ai-notify init        # インストール済みのエージェントを自動
 - 🔕 **1スイッチで全部ミュート。** 全エージェント・全ターミナルが同じフラグを読むので、会議中はワンタップで全部静かに。
 - 🔔 **ネイティブのメニューバーも内蔵。** `ai-notify menubar install` — Hammerspoon/SwiftBar 不要。
 
+エージェントの返答を翻訳・VOICEVOX キャラの一覧・ツンデレ口調のクイックツアー：
+
+![ai-notify の機能: 翻訳・VOICEVOXボイス・ツンデレ](https://raw.githubusercontent.com/unoryota/ai-notify/main/assets/features.gif)
+
 ## 対応エージェント
 
 | エージェント | 状態 | 配線方法 |
@@ -68,9 +82,17 @@ ai-notify menubar install   # ネイティブのメニューバーアプリ・
 
 モノクロの波形アイコンが**状態を色で**表します（Adobe風）：通常はシルエットのみ、入力待ちがあると**黄ドット**、ミュート中は**赤＋斜線**。
 
-- **左クリック** → メニュー：**音量スライダー**、**ツンデレ**トグル＋デレ⇄ツンスライダー、**声の一覧**（システム＋VOICEVOX）、**ペイン別**設定（開いている各ターミナルに個別の声と音量）。
+- **左クリック** → メニュー：**音量スライダー**、**ツンデレ**トグル＋デレ⇄ツンスライダー、**声の一覧**（システム＋VOICEVOX）、**ペイン別**設定。開いている各ターミナルに、**読み上げ名**（どのペインが終わったか声で分かる）・**声**・**音量**を個別設定でき、各行にそのペインの声が一覧表示されます。
 - **右クリック** → 即ミュート切替。
 
+<p>
+  <img alt="ai-notify メニュー — 音量・ツンデレ・声" src="https://raw.githubusercontent.com/unoryota/ai-notify/main/assets/menubar.png" width="250">
+  &nbsp;&nbsp;
+  <img alt="ペインごとの読み上げ名と声（1ターミナル1行）" src="https://raw.githubusercontent.com/unoryota/ai-notify/main/assets/menubar-panes.png" width="250">
+</p>
+
+*左：全体の音量／ツンデレ／声。右：各ペインに名前と声を割り当て（🗣 バックエンド → Kyoko、infra → ずんだもん）。*
+
 第三者アプリ不要。別の方法が好みなら、**Hammerspoon**・**SwiftBar/xbar**・**Raycast**・標準の**ショートカット**用レシピが [`recipes/`](recipes/) にあります。`ai-notify status --icon` は `🔔`/`🔕` だけを出力するので、tmux・プロンプト・Claude Code のステータスラインに埋め込めます。
 
 > 切替は実行中でも効きます：次にエージェントが発火した時にフラグを読むので、トグルした瞬間に全稼働エージェントへ反映されます。

package/README.md

@@ -2,6 +2,12 @@
 
 **English** · [日本語](README.ja.md)
 
+[![npm](https://img.shields.io/npm/v/ai-notify?color=cb3837&logo=npm)](https://www.npmjs.com/package/ai-notify)
+[![downloads](https://img.shields.io/npm/dw/ai-notify?color=cb3837)](https://www.npmjs.com/package/ai-notify)
+[![license](https://img.shields.io/npm/l/ai-notify?color=blue)](./LICENSE)
+![platform](https://img.shields.io/badge/macOS%20%C2%B7%20Linux-zero--dep-success)
+[![stars](https://img.shields.io/github/stars/unoryota/ai-notify?style=social)](https://github.com/unoryota/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.
 
 ![ai-notify demo](https://raw.githubusercontent.com/unoryota/ai-notify/main/assets/hero-en.gif)
@@ -13,6 +19,11 @@ brew install unoryota/tap/ai-notify   # macOS (Homebrew)
 ai-notify init        # auto-detects your agents and wires them
 ```
 
+That's the whole setup — `init` finds Claude Code / Codex / Gemini and wires
+their hooks. From then on you control everything with one switch:
+
+![ai-notify usage: init, status, one-switch mute, voices](https://raw.githubusercontent.com/unoryota/ai-notify/main/assets/usage.gif)
+
 ## What makes it different
 
 Plenty of agents go quiet for minutes. ai-notify pulls you back at the right moment — and is built for **running many agents at once**:
@@ -23,6 +34,10 @@ Plenty of agents go quiet for minutes. ai-notify pulls you back at the right mom
 - 🔕 **One switch mutes everything.** Every agent in every terminal reads the same flag — one tap silences them all for a meeting.
 - 🔔 **A real menu bar bell, built in.** `ai-notify menubar install` — no Hammerspoon/SwiftBar required.
 
+A quick tour — translate an agent's reply, list VOICEVOX character voices, and the tsundere persona:
+
+![ai-notify features: translate, VOICEVOX voices, tsundere](https://raw.githubusercontent.com/unoryota/ai-notify/main/assets/features.gif)
+
 ## Supported agents
 
 | Agent | Status | How it's wired |
@@ -68,9 +83,17 @@ ai-notify menubar install   # native menu bar app, starts at login
 
 A monochrome waveform icon shows status by color (Adobe-style): plain when idle, a **yellow** dot when an agent is waiting for you, **red + slash** when muted.
 
-- **Left-click** → menu: a **volume slider**, a **tsundere** toggle + デレ⇄ツン slider, the **voice list** (system + VOICEVOX), and **per-pane** controls — each open terminal gets its own voice *and* volume.
+- **Left-click** → menu: a **volume slider**, a **tsundere** toggle + デレ⇄ツン slider, the **voice list** (system + VOICEVOX), and **per-pane** controls. Each open terminal gets its own **spoken name** (read out so you know *which* pane finished), **voice**, and **volume** — the row shows each pane's voice at a glance.
 - **Right-click** → instant mute toggle.
 
+<p>
+  <img alt="ai-notify menu — volume, tsundere, and voice controls" src="https://raw.githubusercontent.com/unoryota/ai-notify/main/assets/menubar.png" width="250">
+  &nbsp;&nbsp;
+  <img alt="per-pane spoken name and voice, one row per terminal" src="https://raw.githubusercontent.com/unoryota/ai-notify/main/assets/menubar-panes.png" width="250">
+</p>
+
+*Left: global volume / tsundere / voices. Right: each pane named and given its own voice (🗣 バックエンド → Kyoko, infra → ずんだもん).*
+
 No third-party app needed. Prefer something else? There are drop-in recipes for **Hammerspoon**, **SwiftBar/xbar**, **Raycast**, and the built-in **macOS Shortcuts** in [`recipes/`](recipes/). `ai-notify status --icon` prints just `🔔`/`🔕` to embed in tmux / your prompt / Claude Code's status line.
 
 > Toggling works mid-run: the flag is read the next time an agent fires, so flipping it instantly affects every running agent.

package/menubar/AiNotifyMenuBar.swift

@@ -113,6 +113,13 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         }
         render()
         timer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { [weak self] _ in self?.render() }
+
+        var shotPath = ProcessInfo.processInfo.environment["AI_NOTIFY_SHOT"]
+        let args = CommandLine.arguments
+        if let i = args.firstIndex(of: "--shot"), i + 1 < args.count { shotPath = args[i + 1] }
+        if let shot = shotPath, !shot.isEmpty {
+            DispatchQueue.main.asyncAfter(deadline: .now() + 0.5) { [weak self] in self?.captureMenuShot(shot) }
+        }
     }
 
     // Black/white waveform silhouette (template, auto-adapting) when idle; a
@@ -175,6 +182,28 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
     @objc private func paneVolumeChanged(_ s: NSSlider) {
         if let tty = s.identifier?.rawValue { State.cli(["volume-pane", tty, String(format: "%.2f", s.doubleValue)]) }
     }
+    // Editing a text field *inside* an NSMenu is unreliable — the menu's tracking
+    // loop swallows the keystrokes. So naming a pane opens a normal modal dialog
+    // (NSAlert with a text field), which takes keyboard focus properly. Empty =>
+    // clear (the pane falls back to its label / the speakLabel default).
+    @objc private func promptPaneName(_ sender: NSMenuItem) {
+        guard let info = sender.representedObject as? [String], let tty = info.first else { return }
+        let current = info.count > 1 ? info[1] : ""
+        let alert = NSAlert()
+        alert.messageText = "読み上げ名"
+        alert.informativeText = "このペインを通知で読み上げる名前（空欄で解除）"
+        let field = NSTextField(frame: NSRect(x: 0, y: 0, width: 240, height: 24))
+        field.stringValue = current
+        field.placeholderString = "例: バックエンド"
+        alert.accessoryView = field
+        alert.addButton(withTitle: "保存")
+        alert.addButton(withTitle: "キャンセル")
+        NSApp.activate(ignoringOtherApps: true)
+        alert.window.initialFirstResponder = field
+        guard alert.runModal() == .alertFirstButtonReturn else { return }
+        let name = field.stringValue.trimmingCharacters(in: .whitespacesAndNewlines)
+        State.cli(["name-pane", tty, name.isEmpty ? "clear" : name])
+    }
     // identifier carries the prosody key (speed | pitch | intonation).
     @objc private func prosodyChanged(_ s: NSSlider) {
         if let key = s.identifier?.rawValue { State.cli(["voice-prosody", key, String(format: "%.3f", s.doubleValue)]) }
@@ -261,7 +290,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         return it
     }
 
-    private func showMenu() {
+    private func buildMenu() -> NSMenu {
         let menu = NSMenu()
 
         // Parse menu-json once.
@@ -323,8 +352,30 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
                 guard let tty = p["tty"] as? String else { continue }
                 let label = p["label"] as? String ?? tty
                 let cur = p["current"] as? String
-                let item = NSMenuItem(title: cur != nil ? "\(label) — \(cur!)" : label, action: nil, keyEquivalent: "")
+                let pname = p["speakName"] as? String ?? ""
+                // Parent row shows at a glance WHO the pane is (its custom 🗣 name,
+                // or its label/tty) AND which 🔊 voice it uses (omitted when it just
+                // follows the global voice). Naming a pane must not hide the voice —
+                // surfacing the per-pane voice is what this list is for.
+                let who = pname.isEmpty ? label : "🗣 \(pname)"
+                let voiceTag = cur != nil ? " — 🔊 \(cur!)" : ""
+                let item = NSMenuItem(title: who + voiceTag, action: nil, keyEquivalent: "")
                 let sub = NSMenu()
+                // Per-pane spoken name — opens a dialog (menu fields can't type).
+                sub.addItem(disabledHeader("読み上げ名"))
+                let nameItem = NSMenuItem(
+                    title: pname.isEmpty ? "（クリックして設定…）" : "「\(pname)」を変更…",
+                    action: #selector(promptPaneName(_:)), keyEquivalent: ""
+                )
+                nameItem.target = self
+                nameItem.representedObject = [tty, pname]
+                sub.addItem(nameItem)
+                if !pname.isEmpty {
+                    let clr = NSMenuItem(title: "読み上げ名を解除", action: #selector(runItem(_:)), keyEquivalent: "")
+                    clr.target = self; clr.representedObject = ["name-pane", tty, "clear"]
+                    sub.addItem(clr)
+                }
+                sub.addItem(.separator())
                 // Per-pane volume.
                 let pv = (p["volume"] as? Double) ?? State.volume
                 sub.addItem(disabledHeader("音量"))
@@ -359,6 +410,59 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         quitItem.target = self
         menu.addItem(quitItem)
 
+        return menu
+    }
+
+    private func showMenu() {
+        let menu = buildMenu()
+        if let button = statusItem.button {
+            menu.popUp(positioning: nil, at: NSPoint(x: 0, y: button.bounds.height + 4), in: button)
+        }
+    }
+
+    // Screenshot mode (env AI_NOTIFY_SHOT=/path): open the menu, capture just its
+    // window via `screencapture`, then quit. Used to regenerate the README image
+    // headlessly — never reached in normal operation.
+    private var shotMenu: NSMenu?
+    func captureMenuShot(_ path: String) {
+        let menu = buildMenu()
+        shotMenu = menu
+        let pid = ProcessInfo.processInfo.processIdentifier
+        // An open NSMenu runs the runloop in event-tracking mode, so the timer
+        // must be registered in .common mode to fire while the menu is on screen.
+        // The menu window can take a few ticks to register with the window
+        // server, so poll for it rather than assuming a single fixed delay.
+        var ticks = 0
+        let t = Timer(timeInterval: 0.25, repeats: true) { [weak self] timer in
+            ticks += 1
+            let infos = (CGWindowListCopyWindowInfo([.optionOnScreenOnly], kCGNullWindowID) as? [[String: Any]]) ?? []
+            var bestId: CGWindowID = 0
+            var bestArea: CGFloat = 0
+            for w in infos {
+                guard (w[kCGWindowOwnerPID as String] as? pid_t) == pid else { continue }
+                guard let b = w[kCGWindowBounds as String] as? [String: CGFloat],
+                      let wd = b["Width"], let ht = b["Height"],
+                      let num = w[kCGWindowNumber as String] as? Int else { continue }
+                // The menu is far taller than the status-bar button window.
+                let area = wd * ht
+                if ht > 120 && area > bestArea { bestArea = area; bestId = CGWindowID(num) }
+            }
+            if bestId == 0 && ticks < 16 { return } // menu window not up yet — keep polling
+            if bestId != 0 {
+                // -l captures the window at native resolution and crops tight to
+                // it; -o drops the drop-shadow for a clean asset.
+                let p = Process()
+                p.launchPath = "/usr/sbin/screencapture"
+                p.arguments = ["-x", "-o", "-l", String(bestId), path]
+                try? p.run(); p.waitUntilExit()
+            }
+            timer.invalidate()
+            menu.cancelTracking()
+            self?.shotMenu = nil
+            NSApp.terminate(nil)
+        }
+        RunLoop.main.add(t, forMode: .common)
+        NSApp.activate(ignoringOtherApps: true) // a popUp only shows for the active app
         if let button = statusItem.button {
             menu.popUp(positioning: nil, at: NSPoint(x: 0, y: button.bounds.height + 4), in: button)
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-notify",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "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": {

package/src/cli.mjs

@@ -32,6 +32,7 @@ import {
   readPanes,
   readPaneSetting,
   updatePaneSetting,
+  firstRunNudge,
 } from './state.mjs';
 
 // Single source of truth: read the version from package.json so `--version`
@@ -138,7 +139,15 @@ const cmds = {
     }
     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.');
+    if (!dryRun) {
+      log('Restart already-running Codex sessions to pick up the change.');
+      // A quiet, one-time nudge — `init` is a setup command, run once. Shown
+      // only on the first successful wiring so it never nags on re-runs.
+      if (any && firstRunNudge()) {
+        log('\n⭐ Useful? A GitHub star really helps it reach others:');
+        log('   https://github.com/unoryota/ai-notify');
+      }
+    }
   },
 
   uninstall() {
@@ -479,6 +488,24 @@ const cmds = {
     log(`pane ${tty}: tsundere level ${v}`);
   },
 
+  // Name a specific pane in the spoken read-out (set from the menu bar), or
+  // `clear` to fall back to the label / speakLabel default.
+  //   name-pane <tty> <name|clear>
+  'name-pane'() {
+    const [tty, ...rest] = positionals;
+    const arg = rest.join(' ').trim(); // a name may contain spaces
+    if (!tty || arg === '') {
+      console.error('usage: name-pane <tty> <name|clear>');
+      process.exit(1);
+    }
+    if (arg === 'clear') {
+      updatePaneSetting(tty, { speakName: null });
+      return log(`pane ${tty}: name cleared`);
+    }
+    updatePaneSetting(tty, { speakName: arg });
+    log(`pane ${tty}: name ${arg}`);
+  },
+
   // Get/set the VOICEVOX base prosody (the normal-tone scales the menu bar
   // sliders drive). With no args, prints the current values as JSON.
   //   voice-prosody [speed|pitch|intonation <value> | reset]
@@ -534,6 +561,7 @@ const cmds = {
         tty,
         label: recorded.get(tty) || tty.replace('/dev/', ''),
         current: labelFor(s.tts ? s : null),
+        speakName: typeof s.speakName === 'string' ? s.speakName : '',
         volume: typeof s.volume === 'number' ? s.volume : globalVol,
         volumeSet: typeof s.volume === 'number',
         tsundere: typeof s.tsundere === 'number' ? s.tsundere : tsLevel,

package/src/notify.mjs

@@ -176,19 +176,21 @@ export const emit = ({ provider = 'default', event = 'done', label = '', message
   if (!message) spokenBody = fromTemplate || fallback;
   else if (config.speakAgentMessage) spokenBody = fullBody;
   else spokenBody = shortenForSpeech(fullBody, config.speakMaxChars || 40);
-  // The task gist already tells you which pane; the label (often the working
-  // dir) is just slow filler. Prefix it only if explicitly enabled.
-  const speakText = config.speakLabel === true && label ? `${label}、${spokenBody}` : spokenBody;
-
-  // Per-pane voice: remember this pane (so the menu bar can list it) and apply
-  // any voice assigned to it. Precedence (most specific first):
-  //   $AI_NOTIFY_* env  — set in the pane's shell
-  //   this pane's pick  — assigned from the menu bar (keyed by tty)
-  //   provider / global — config defaults
+  // Per-pane settings (voice / volume / tsundere / name), keyed by tty. Read
+  // here — before the read-out is assembled — so the spoken text can use this
+  // pane's assigned name. Also remember the pane so the menu bar can list it.
   const tty = controllingTty();
   recordPane(tty, label);
   setPaneWaiting(tty, event === 'waiting'); // waiting -> yellow menu bar status; done clears it
   const pane = readPaneSetting(tty);
+
+  // Name this pane in the read-out. An explicit per-pane name (set from the menu
+  // bar) is ALWAYS spoken; the auto-derived label (often just the working dir)
+  // is prefixed only when speakLabel is on — it's slow filler otherwise.
+  const spokenName = pane.speakName || (config.speakLabel === true && label ? label : '');
+  const speakText = spokenName ? `${spokenName}、${spokenBody}` : spokenBody;
+
+  // Per-pane voice (precedence: $AI_NOTIFY_* env > this pane's pick > global).
   const tts = pane.tts || config.tts;
   const voice = process.env.AI_NOTIFY_VOICE || pane.voice || p.voice || config.voice;
   const speaker = process.env.AI_NOTIFY_VOICEVOX_SPEAKER || pane.speaker || config.voicevox?.speaker;
@@ -231,7 +233,7 @@ export const emit = ({ provider = 'default', event = 'done', label = '', message
     speakTone = tsundere.axisFor(eff);
     outVol = Math.min(2, Math.max(0, vol * tsundere.volumeMul(tier, ts.volumeBoost !== false)));
     outText = tsundere.wrap(spokenBody, eff, tier, ts.lang || 'ja', nextCounter('tsundere'));
-    if (config.speakLabel === true && label) outText = `${label}、${outText}`;
+    if (spokenName) outText = `${spokenName}、${outText}`;
     if (tts === 'voicevox') {
       const sm = ts.styleMap || voicevox.resolveStyles(outSpeaker, config.voicevox?.url);
       const axis = tsundere.axisFor(eff);

package/src/state.mjs

@@ -159,6 +159,23 @@ export const nextCounter = (name) => {
   return n;
 };
 
+// One-time UI nudges (e.g. the post-`init` star hint). Returns true the FIRST
+// time it's called for a given key, then records a marker so it never fires
+// again — so setup hints inform once without ever nagging on re-runs.
+export const firstRunNudge = (key = 'star') => {
+  const p = join(stateDir(), `nudged-${key}`);
+  if (existsSync(p)) return false;
+  try {
+    ensureDir(stateDir());
+    writeFileSync(p, '');
+  } catch {
+    /* best-effort: if we can't persist, don't nag repeatedly is preferred, so
+       treat a write failure as "already shown". */
+    return false;
+  }
+  return true;
+};
+
 // --- Per-pane state --------------------------------------------------------
 // Recently-active terminal panes (so the menu bar can offer per-pane voices),
 // and a per-tty voice override. Both are small JSON files in the state dir.