ai-notify 0.4.3 → 0.4.5

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
@@ -283,7 +290,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         return it
     }
 
-    private func showMenu() {
+    private func buildMenu() -> NSMenu {
         let menu = NSMenu()
 
         // Parse menu-json once.
@@ -403,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.3",
+  "version": "0.4.5",
   "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() {

package/src/notify.mjs

@@ -184,10 +184,15 @@ export const emit = ({ provider = 'default', event = 'done', label = '', message
   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 : '');
+  // Name this pane in the read-out, most-reliable identity first:
+  //   1. $AI_NOTIFY_LABEL — set in the pane's shell, inherited by the hook even
+  //      when the agent runs it detached (no tty). Always spoken: setting it is
+  //      explicit intent. The reliable way to name a pane for Claude Code.
+  //   2. pane.speakName — set from the menu bar, keyed by tty. Works only when
+  //      the hook resolves to the pane's tty (see controllingTty's tree walk).
+  //   3. the auto-derived label — only when speakLabel is on (else slow filler).
+  const envName = (process.env.AI_NOTIFY_LABEL || '').trim();
+  const spokenName = envName || 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).

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.

package/src/util.mjs

@@ -40,18 +40,34 @@ export const isEphemeralInstall = (cliPath) => /[/\\]_npx[/\\]/.test(cliPath);
 
 export const MARKER = 'ai-notify'; // substring used to detect our own wiring
 
-// The controlling terminal of this process (e.g. "/dev/ttys010"), which is
-// stable per terminal pane — used to scope per-pane settings. null if none.
+// The controlling terminal of the agent's pane (e.g. "/dev/ttys010"), used to
+// scope per-pane settings. Returns null if none can be found.
+//
+// Agents often run the notify hook detached (Claude Code wires it `async`), so
+// the hook process itself frequently has NO controlling tty — but its parent
+// (the agent, e.g. `claude`) still owns the pane's terminal. So we walk up the
+// process tree until we find a real tty, which makes the hook resolve to the
+// SAME tty the menu bar lists the pane under (it scans the agent process).
 export const controllingTty = () => {
-  try {
-    const t = execFileSync('ps', ['-o', 'tty=', '-p', String(process.pid)], {
-      stdio: ['ignore', 'pipe', 'ignore'],
-    })
-      .toString()
-      .trim();
-    if (!t || t === '??' || t === '?') return null;
-    return t.startsWith('/dev/') ? t : `/dev/${t}`;
-  } catch {
-    return null;
+  let pid = process.pid;
+  for (let depth = 0; depth < 8 && pid > 1; depth++) {
+    try {
+      const line = execFileSync('ps', ['-o', 'tty=', '-o', 'ppid=', '-p', String(pid)], {
+        stdio: ['ignore', 'pipe', 'ignore'],
+      })
+        .toString()
+        .trim();
+      if (!line) return null;
+      // "ttys010  1234"  or  "??  1234" (no controlling tty for this pid)
+      const sp = line.lastIndexOf(' ');
+      const tty = line.slice(0, sp).trim();
+      const ppid = parseInt(line.slice(sp + 1).trim(), 10);
+      if (tty && tty !== '??' && tty !== '?') return tty.startsWith('/dev/') ? tty : `/dev/${tty}`;
+      if (!Number.isFinite(ppid) || ppid <= 1) return null;
+      pid = ppid;
+    } catch {
+      return null;
+    }
   }
+  return null;
 };