claude-code-popup 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tom-Canon-Rock
+
+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,240 @@
+# claude-code-popup
+
+Claude Code (CLI) の Notification フックが発火したときに、デスクトップへカスタムデザインのポップアップを表示するツールです。
+
+## 特長
+
+- 複数の Claude Code セッションをカード形式で同時表示（3 件まで自動伸縮、それ以上スクロール）
+- カード本体クリックで起動元ターミナルを前面に呼び戻し
+- ヘッダーから設定 GUI 起動（⚙）／カード一括消去（×）
+- 5 種類のデザインテーマ
+- マルチモニター対応（カーソルがあるディスプレイへ表示）
+- `SessionEnd` フックと連動して Electron プロセスを自動停止
+
+## インストール
+
+### npm（公開後）
+
+```sh
+npm install -g claude-code-popup
+```
+
+`postinstall` で `~/.claude/settings.json` にフックが自動登録されます。
+
+### 開発インストール
+
+```sh
+git clone <repo>
+cd claude-code-popup
+npm install
+npm link                 # PATH に claude-code-popup を登録
+claude-code-popup setup      # 設定 GUI とフック登録を一括実行
+```
+
+解除：
+
+```sh
+npm unlink -g claude-code-popup
+```
+
+---
+
+## 使用手順
+
+### 1. 初回セットアップ
+
+グローバルインストールした場合、フックは自動登録されています。`claude-code-popup setup` を一度だけ実行して、デザイン・位置・表示時間などをお好みに調整してください。
+
+```sh
+claude-code-popup setup
+```
+
+### 2. 通常運用
+
+以降は意識する必要はありません。Claude Code の各セッションで以下が自動実行されます。
+
+| Claude Code フック | claude-code-popup 動作 |
+|--------------------|---------------------|
+| `SessionStart`    | Electron をバックグラウンド起動（既起動ならスキップ） |
+| `Notification`（`permission_prompt`） | 通知ウィンドウにカードを追加 |
+| `SessionEnd`      | 該当セッションのカードを削除。最後のセッションだったら Electron も終了 |
+
+### 3. 通知が来たとき
+
+| 操作 | 結果 |
+|------|------|
+| カード本体をクリック | 起動元ターミナルを前面に |
+| カード右上の `×` | 該当カードのみ削除 |
+| ヘッダーの `×` | 全カード一括削除 |
+| ヘッダーの `⚙` | 設定 GUI を起動 |
+
+---
+
+## 設定 GUI の表示
+
+`claude-code-popup setup` で表示される 1 ページ UI です。各項目は変更後「設定を保存」を押すまで適用されません。
+
+設定 GUI の表示言語は **OS のロケール** に追従します（現在 `ja` / `en` 対応、それ以外は `en`）。
+
+| セクション | 内容 | 備考 |
+|------------|------|------|
+| 通知デザイン | 5 種類のグリッドから選択。下にプレビュー | クリック即反映 |
+| 通知メッセージ | カードに表示するタイトル文 | 空のままなら OS ロケールに応じた既定文を使用 |
+| 表示位置 | 右下／左下／右上／左上のセレクト | カーソルがあるディスプレイ基準 |
+| 表示時間 | 0〜60 秒のスライダー | `0` で自動消去なし／タイマーバーも非表示 |
+| サウンド | 通知音オン／オフ | OS の通知音 API を利用 |
+
+### 5 つのデザイン
+
+| # | 名前 | 特徴 |
+|---|------|------|
+| 1 | ミニマル | 白ベース、シャドウ控えめ |
+| 2 | アクセントバー・ダーク | ダークカード＋左サイドにカラーバー |
+| 3 | Claude カラー | オレンジヘッダー帯 |
+| 4 | ライト＋アクセントバー | ライトカード＋左サイドにカラーバー |
+| 5 | ダーク | ダークカード、シンプル |
+
+タイマーバーはすべてのデザインで `duration > 0` のとき自動表示されます。
+
+---
+
+## CLI コマンド
+
+| コマンド | 用途 |
+|----------|------|
+| `claude-code-popup setup` | 設定 GUI を起動。フックも併せて確認・登録 |
+| `claude-code-popup start --dir <path>` | 通知デーモンを起動（`SessionStart` フック用） |
+| `claude-code-popup send --dir <path>` | 通知ウィンドウへカード追加（`Notification` フック用） |
+| `claude-code-popup end --dir <path>` | 該当セッションのカードを削除し、最後のセッションだった場合はデーモンを終了（`SessionEnd` フック用） |
+| `claude-code-popup help` | ヘルプ |
+
+`send` は Electron が起動していなければ自動起動します（フック以外から手動でも使えます）。
+
+---
+
+## 設定ファイル
+
+`~/.claude-code-popup/config.json`
+
+```json
+{
+  "design": 1,
+  "message": {
+    "title": ""
+  },
+  "position": "bottom-right",
+  "duration": 5,
+  "sound": false
+}
+```
+
+| キー | 型 | 説明 |
+|------|----|------|
+| `design` | `1〜5` | デザインプリセット番号 |
+| `message.title` | string | カードに表示するタイトル文。空文字なら OS ロケールに応じた既定文を使用 |
+| `position` | `"top-left" \| "top-right" \| "bottom-left" \| "bottom-right"` | 表示位置 |
+| `duration` | number (秒) | 自動消去までの秒数。`0` で消えない（タイマーバーも非表示） |
+| `sound` | boolean | 通知音の有無 |
+
+ランタイム情報（PID／IPC ポート）は `~/.claude-code-popup/runtime.json` に保存され、Electron 起動の重複防止に使われます。Electron 終了時に自動削除されます。
+
+---
+
+## 使用上の注意
+
+### 起動時の遅延
+
+Electron のコールドスタートに **1〜3 秒** ほどかかります。`SessionStart` フックで先回り起動する設計のため、`Notification` フック発火時の通知表示はほぼ即座になります。手動で `send` だけ叩いた場合は、初回のみウィンドウ表示まで待ち時間があります。
+
+### プロセスのライフサイクル
+
+- **通常時**: Electron プロセスは存在しません
+- **Claude Code 起動中**: 1 つだけバックグラウンドで動作（複数セッションでも 1 プロセス）
+- **全セッション終了時**: 自動的に終了
+
+手動で `claude-code-popup start` を叩いた場合、対応する `end` を発行するか手動で kill するまでデーモンが残り続けます。テスト用途では注意してください。
+
+```powershell
+# 残ってしまった場合の手動終了（Windows）
+Get-Process electron -ErrorAction SilentlyContinue | Stop-Process -Force
+```
+
+### マルチモニター環境
+
+通知ウィンドウは `claude-code-popup send` 実行時点での **マウスカーソルがあるディスプレイ** に表示されます。期待と違うモニターに出る場合はカーソルの位置を確認してください。
+
+### フックの取り扱い
+
+`~/.claude/settings.json` を `installHooks` / `uninstallHooks` で編集します。
+
+- 既存の他のフックは保持されます（`claude-code-popup` 関連だけマージ）
+- ファイルが存在しない場合は新規作成されます
+- グローバル install / uninstall 時に自動実行されます（`postinstall` / `preuninstall`）
+- `npm link` での開発インストールでは `postinstall` は走らないため、`claude-code-popup setup` で手動登録してください
+
+### `claude-code-popup` コマンドが PATH に通っていない場合
+
+フックは裸の `claude-code-popup` を呼ぶため、PATH に通っていないと **Claude Code 側ではフックが silent fail** します。`Get-Command claude-code-popup`（PowerShell）／`which claude-code-popup`（bash）で確認できます。
+
+### ターミナル前面化の制約
+
+| OS | 動作 |
+|----|------|
+| Windows | 親プロセス（cmd / PowerShell / Windows Terminal / VS Code 統合ターミナルなど）を遡り、最初に MainWindow を持つプロセスを `SetForegroundWindow` で前面化 |
+| macOS | `Terminal.app` を `osascript` で activate（best effort） |
+| Linux | `wmctrl` 依存（インストールが必要な場合あり） |
+
+VS Code や JetBrains の統合ターミナルから Claude Code を起動している場合、前面化されるのは IDE 全体のウィンドウになります。
+
+### 透明ウィンドウのレンダリング
+
+通知ウィンドウは `transparent: true` の Electron BrowserWindow です。ごく稀に GPU ドライバ起因で描画されない場合があります。その場合：
+
+```powershell
+# Electron をリセットして再起動
+Get-Process electron -ErrorAction SilentlyContinue | Stop-Process -Force
+Remove-Item ~/.claude-code-popup/runtime.json -ErrorAction SilentlyContinue
+```
+
+その後、新しい Claude Code セッションを開いて再現するか確認してください。
+
+---
+
+## ディレクトリ構成
+
+```
+claude-code-popup/
+├── bin/
+│   ├── cli.js                CLI エントリポイント
+│   ├── postinstall.js        グローバル install 時にフック登録
+│   └── preuninstall.js       グローバル uninstall 時にフック解除
+├── src/
+│   ├── config.js             ~/.claude-code-popup/config.json 読み書き
+│   ├── hooks.js              ~/.claude/settings.json のフック登録/解除
+│   ├── ipc.js                CLI ↔ Electron 間の TCP/JSON プロトコル
+│   └── runtime.js            ロックファイル / プロセス存在確認
+└── electron/
+    ├── main.js               IPC サーバ + ウィンドウ管理
+    ├── preload.js            contextBridge 経由の IPC ブリッジ
+    ├── notify.html / .js / .css   通知ウィンドウ
+    └── setup.html / .js / .css    設定 GUI
+```
+
+## 対応 OS
+
+| OS | 状態 |
+|----|------|
+| Windows | 動作確認済み |
+| macOS | 通知 UI 動作。ターミナル前面化は Terminal.app 限定 |
+| Linux | 通知 UI 動作。ターミナル前面化は `wmctrl` 依存 |
+
+## 今後の予定
+
+- npm レジストリへの公開
+- ユーザー独自デザインの追加機能
+- 通知履歴ログ
+- macOS / Linux のターミナル前面化精度向上
+
+## ライセンス
+
+MIT

package/bin/cli.js

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+
+const ipc = require('../src/ipc');
+const runtime = require('../src/runtime');
+const { installHooks } = require('../src/hooks');
+const { CONFIG_PATH } = require('../src/config');
+
+function getForegroundHwnd() {
+  if (process.platform !== 'win32') return null;
+  try {
+    const ps =
+      "Add-Type -MemberDefinition '[DllImport(\"user32.dll\")] public static extern IntPtr GetForegroundWindow();' -Name F -Namespace Win -ErrorAction SilentlyContinue; [Win.F]::GetForegroundWindow().ToInt64()";
+    const r = spawnSync('powershell.exe', ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-Command', ps], {
+      encoding: 'utf8',
+      windowsHide: true,
+      timeout: 4000,
+    });
+    const n = parseInt((r.stdout || '').trim(), 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  } catch {
+    return null;
+  }
+}
+
+const ROOT = path.resolve(__dirname, '..');
+const ELECTRON_ENTRY = path.join(ROOT, 'electron', 'main.js');
+
+function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        args.flags[key] = true;
+      } else {
+        args.flags[key] = next;
+        i++;
+      }
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+function resolveElectronBinary() {
+  try {
+    return require('electron');
+  } catch (err) {
+    console.error('[claude-code-popup] electron is not installed. Run: npm install');
+    throw err;
+  }
+}
+
+function spawnElectron({ mode } = {}) {
+  const electronPath = resolveElectronBinary();
+  const env = { ...process.env, CLAUDE_NOTIFY_MODE: mode || 'notify' };
+  const child = spawn(electronPath, [ELECTRON_ENTRY], {
+    detached: true,
+    stdio: 'ignore',
+    env,
+    windowsHide: true,
+  });
+  child.unref();
+  return child;
+}
+
+async function waitForServer({ tries = 40, intervalMs = 150 } = {}) {
+  for (let i = 0; i < tries; i++) {
+    const info = await runtime.getRunningInstance();
+    if (info) return info;
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  return null;
+}
+
+async function ensureRunning(mode) {
+  const existing = await runtime.getRunningInstance();
+  if (existing) return existing;
+  spawnElectron({ mode });
+  const ready = await waitForServer();
+  if (!ready) throw new Error('failed_to_start_electron');
+  return ready;
+}
+
+async function cmdSetup() {
+  // Hooks are normally installed automatically by the npm postinstall script.
+  // For dev (npm link) flows, run it here too so the UI is fully wired up.
+  const settingsPath = installHooks();
+  console.log(`[claude-code-popup] config        -> ${CONFIG_PATH}`);
+  console.log(`[claude-code-popup] hooks ensured -> ${settingsPath}`);
+  spawnElectron({ mode: 'setup' });
+}
+
+async function cmdStart(args) {
+  const dir = args.flags.dir && args.flags.dir !== true ? String(args.flags.dir) : '';
+  const hwnd = getForegroundHwnd();
+  const info = await ensureRunning('notify');
+  if (dir) {
+    try {
+      await ipc.send(info.port, { type: 'start', dir, ppid: process.ppid, hwnd });
+    } catch {
+      /* ignore */
+    }
+  }
+  console.log(`[claude-code-popup] running on port ${info.port} (pid ${info.pid})`);
+}
+
+async function cmdSend(args) {
+  const dir = args.flags.dir;
+  if (!dir || dir === true) {
+    console.error('[claude-code-popup] --dir <path> is required');
+    process.exit(1);
+  }
+  const info = await ensureRunning('notify');
+  // Also send hwnd on `send` so manual `send` calls (without prior `start`) still work.
+  // For real Claude Code flow, start has already populated sessionHwnd, but we update
+  // here too in case the user moved between terminals.
+  const hwnd = getForegroundHwnd();
+  await ipc.send(info.port, { type: 'send', dir: String(dir), ppid: process.ppid, hwnd });
+}
+
+async function cmdEnd(args) {
+  const dir = args.flags.dir;
+  if (!dir || dir === true) {
+    console.error('[claude-code-popup] --dir <path> is required');
+    process.exit(1);
+  }
+  const info = await runtime.getRunningInstance();
+  if (!info) return;
+  try {
+    await ipc.send(info.port, { type: 'end', dir: String(dir) });
+  } catch {
+    /* electron may have already exited */
+  }
+}
+
+function printHelp() {
+  console.log(`claude-code-popup <command> [options]
+
+Commands:
+  setup                       Launch settings GUI and install Claude Code hooks
+  start                       Start the notification daemon (idempotent)
+  send --dir <path>           Add a notification card for the given directory
+  end  --dir <path>           Remove the notification card for the given directory
+  help                        Show this message
+`);
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0];
+  try {
+    switch (cmd) {
+      case 'setup':
+        await cmdSetup();
+        break;
+      case 'start':
+        await cmdStart(args);
+        break;
+      case 'send':
+        await cmdSend(args);
+        break;
+      case 'end':
+        await cmdEnd(args);
+        break;
+      case 'help':
+      case undefined:
+        printHelp();
+        break;
+      default:
+        console.error(`[claude-code-popup] unknown command: ${cmd}`);
+        printHelp();
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(`[claude-code-popup] ${err?.message || err}`);
+    process.exit(1);
+  }
+}
+
+main();

package/bin/postinstall.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+'use strict';
+
+// Only run when this package is installed globally — local/dev installs
+// (npm install <pkg> in a project, or npm install inside this repo) should
+// NOT modify the user's ~/.claude/settings.json.
+if (!process.env.npm_config_global) {
+  process.exit(0);
+}
+
+try {
+  const { installHooks, SETTINGS_PATH } = require('../src/hooks');
+  installHooks();
+  console.log(`[claude-code-popup] Claude Code hooks installed -> ${SETTINGS_PATH}`);
+  console.log('[claude-code-popup] Run "claude-code-popup setup" to configure the notification UI.');
+} catch (err) {
+  console.error('[claude-code-popup] hook install skipped:', err?.message || err);
+}

package/bin/preuninstall.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+'use strict';
+
+if (!process.env.npm_config_global) {
+  process.exit(0);
+}
+
+try {
+  const { uninstallHooks, SETTINGS_PATH } = require('../src/hooks');
+  uninstallHooks();
+  console.log(`[claude-code-popup] Claude Code hooks removed from ${SETTINGS_PATH}`);
+} catch (err) {
+  console.error('[claude-code-popup] hook uninstall skipped:', err?.message || err);
+}