よくある質問：パフォーマンス、プライバシー、互換性

このレッスンで学べること

• プラグインのパフォーマンスへの影響とリソース消費を理解する
• プライバシーセキュリティの保証を明確にする
• 通知戦略と設定テクニックを習得する
• プラットフォーム間の差異と互換性を理解する

---

パフォーマンス関連

AI コンテキストが増加しますか？

いいえ。プラグインはイベント駆動モデルを使用しており、AI の会話にツールやプロンプトを一切追加しません。

ソースコードの実装から見ると：

コンポーネント	タイプ	実装	コンテキストへの影響
イベントリスナー	イベント	session.idle、session.error、permission.updated イベントを監視	✅ 影響なし
ツールフック	フック	tool.execute.before で question ツールを監視	✅ 影響なし
会話内容	-	会話内容の読み取り、変更、注入は一切なし	✅ 影響なし

ソースコードでは、プラグインは監視と通知のみを担当し、AI 会話のコンテキストには全く影響しません。

システムリソースはどのくらい消費しますか？

極めて少量です。プラグインは「起動時キャッシュ + イベントトリガー」設計を採用しています：

1. 設定読み込み：プラグイン起動時に設定ファイル（~/.config/opencode/kdco-notify.json）を一度だけ読み込み、以降は読み込みません
2. ターミナル検出：起動時にターミナルタイプを検出し情報をキャッシュ（名前、Bundle ID、プロセス名）、以降のイベントではキャッシュを直接使用
3. イベント駆動：AI が特定のイベントをトリガーした時のみ、プラグインが通知ロジックを実行

リソース消費の特徴：

リソースタイプ	消費量	説明
CPU	ほぼ 0	イベントトリガー時のみ短時間実行
メモリ	< 5 MB	起動後はスタンバイ状態
ディスク	< 100 KB	設定ファイルとコード本体
ネットワーク	0	ネットワークリクエストは一切なし

---

プライバシーとセキュリティ

データはサーバーにアップロードされますか？

いいえ。プラグインは完全にローカルで動作し、データのアップロードは一切行いません。

プライバシー保証：

データタイプ	処理方法	アップロード
AI 会話内容	読み取り・保存なし	❌ なし
セッション情報（タイトル）	通知テキストにのみ使用	❌ なし
エラー情報	通知テキストにのみ使用（最大 100 文字）	❌ なし
ターミナル情報	ローカルで検出しキャッシュ	❌ なし
設定情報	ローカルファイル（~/.config/opencode/）	❌ なし
通知内容	システムネイティブ通知 API 経由で送信	❌ なし

技術的実装：

プラグインはシステムネイティブ通知を使用：

• macOS：node-notifier 経由で NSUserNotificationCenter を呼び出し
• Windows：node-notifier 経由で SnoreToast を呼び出し
• Linux：node-notifier 経由で notify-send を呼び出し

すべての通知はローカルでトリガーされ、OpenCode のクラウドサービスを経由しません。

プラグインがセッション内容を盗み見ることはありますか？

いいえ。プラグインは必要最小限のメタデータのみを読み取ります：

読み取るデータ	用途	制限
セッションタイトル（title）	通知テキスト	先頭 50 文字のみ
エラー情報（error）	通知テキスト	先頭 100 文字のみ
ターミナル情報	フォーカス検出とクリック時のフォーカス移動	ターミナル内容は読み取らない
設定ファイル	ユーザーカスタム設定	ローカルファイル

ソースコードには、会話メッセージ（messages）やユーザー入力（user input）を読み取るロジックは一切ありません。

---

通知戦略

通知の嵐に見舞われませんか？

いいえ。プラグインには複数のスマートフィルタリング機構が組み込まれており、通知の嵐を防ぎます。

デフォルト通知戦略：

タイプ	イベント/ツール	通知	理由
イベント	親セッション完了（session.idle）	✅ あり	メインタスク完了
イベント	子セッション完了（session.idle）	❌ なし	親セッションで一括通知
イベント	セッションエラー（session.error）	✅ あり	即時対応が必要
イベント	権限リクエスト（permission.updated）	✅ あり	AI がブロック待機中
ツールフック	質問（tool.execute.before - question）	✅ あり	AI が入力を必要としている

スマートフィルタリング機構：

1. 親セッションのみ通知

   • ソースコード：notify.ts:256-259
   • デフォルト設定：notifyChildSessions: false
   • AI がタスクを分解した際、各サブタスクごとに通知されるのを防止

2. ターミナルフォーカス時の抑制（macOS）

   • ソースコード：notify.ts:265
   • ロジック：ターミナルがフォアグラウンドウィンドウの場合、通知を送信しない（組み込み動作、設定不要）
   • 「ターミナルを見ているのに通知される」という重複リマインドを防止
   • 注意：この機能は macOS でのみ利用可能（ターミナル情報が検出に必要）

3. サイレント時間帯

   • ソースコード：notify.ts:262、notify.ts:181-199
   • デフォルト設定：quietHours: { enabled: false, start: "22:00", end: "08:00" }
   • 設定可能、夜間の邪魔を防止

4. 権限リクエストは常に通知

   • ソースコード：notify.ts:319
   • 理由：AI がユーザーの承認を待ってブロックしているため、即時通知が必要
   • 親セッションチェックなし

特定タイプの通知のみ受け取れますか？

はい。プラグインには個別の通知スイッチはありませんが、サイレント時間帯とターミナルフォーカス検出で実現できます：

• 緊急通知のみ受け取る：ターミナルフォーカス検出は組み込み動作で、ターミナルを見ている時は通知されません（macOS）
• 夜間通知のみ受け取る：サイレント時間帯を有効化（例：09:00-18:00）、逆方向に使用

より細かい制御が必要な場合は、Feature Request の提出をご検討ください。

---

プラグイン互換性

他の OpenCode プラグインと競合しますか？

いいえ。プラグインは標準の OpenCode Plugin API を通じて統合されており、AI の動作を変更したり他のプラグインに干渉したりしません。

統合方法：

コンポーネント	統合方法	競合リスク
イベントリスナー	OpenCode SDK の event フック	❌ 競合なし
ツールフック	OpenCode Plugin API の tool.execute.before フック	❌ 競合なし（question ツールのみ監視）
セッションクエリ	OpenCode SDK の client.session.get()	❌ 競合なし（読み取り専用）
通知送信	node-notifier 独立プロセス	❌ 競合なし

共存可能な他のプラグイン：

• OpenCode 公式プラグイン（例：opencode-coder）
• サードパーティプラグイン（例：opencode-db、opencode-browser）
• カスタムプラグイン

すべてのプラグインは標準の Plugin API を通じて並列実行され、互いに干渉しません。

どのプラットフォームをサポートしていますか？機能に差異はありますか？

macOS、Windows、Linux の 3 大プラットフォームをサポートしていますが、機能に差異があります。

機能	macOS	Windows	Linux
ネイティブ通知	✅ サポート	✅ サポート	✅ サポート
カスタムサウンド	✅ サポート	❌ 非サポート	❌ 非サポート
ターミナルフォーカス検出	✅ サポート	❌ 非サポート	❌ 非サポート
通知クリックでフォーカス移動	✅ サポート	❌ 非サポート	❌ 非サポート
ターミナル自動検出	✅ サポート	✅ サポート	✅ サポート
サイレント時間帯	✅ サポート	✅ サポート	✅ サポート

プラットフォーム差異の理由：

プラットフォーム	差異の説明
macOS	システムが豊富な通知 API とアプリケーション管理インターフェース（osascript など）を提供し、サウンド、フォーカス検出、クリック時のフォーカス移動をサポート
Windows	システム通知 API の機能が限定的で、アプリケーションレベルのフォアグラウンド検出やサウンドカスタマイズをサポートしない
Linux	notify-send 標準に依存し、機能は Windows と同様

クロスプラットフォームのコア機能：

どのプラットフォームを使用しても、以下のコア機能は利用可能です：

• タスク完了通知（session.idle）
• エラー通知（session.error）
• 権限リクエスト通知（permission.updated）
• 質問通知（tool.execute.before）
• サイレント時間帯設定

---

ターミナルとシステム

どのターミナルをサポートしていますか？どのように検出しますか？

37 以上のターミナルエミュレータをサポートしています。

プラグインは detect-terminal ライブラリを使用してターミナルを自動識別します。サポートされるターミナル：

macOS ターミナル：

• Ghostty、Kitty、iTerm2、WezTerm、Alacritty
• macOS Terminal、Hyper、Warp
• VS Code 統合ターミナル（Code / Code - Insiders）

Windows ターミナル：

• Windows Terminal、Git Bash、ConEmu、Cmder
• PowerShell、CMD（デフォルト検出経由）

Linux ターミナル：

• gnome-terminal、konsole、xterm、lxterminal
• terminator、tilix、alacritty、kitty

検出メカニズム：

1. 自動検出：プラグイン起動時に detectTerminal() ライブラリを呼び出し
2. 手動オーバーライド：ユーザーは設定ファイルで terminal フィールドを指定して自動検出を上書き可能
3. macOS マッピング：ターミナル名をプロセス名にマッピング（例：ghostty → Ghostty）、フォーカス検出に使用

設定例：

{
  "terminal": "ghostty"
}

ターミナル検出が失敗した場合はどうなりますか？

プラグインは正常に動作しますが、フォーカス検出機能が無効になります。

失敗時の処理ロジック：

失敗シナリオ	動作	影響
detectTerminal() が null を返す	ターミナル情報が { name: null, bundleId: null, processName: null }	フォーカス検出なし、通知は正常に送信
macOS osascript 実行失敗	Bundle ID 取得失敗	macOS クリック時のフォーカス移動機能が無効、通知は正常
設定ファイルの terminal 値が無効	自動検出結果を使用	自動検出も失敗した場合、フォーカス検出なし

ソースコードの関連ロジック（notify.ts:149-150）：

if (!terminalName) {
  return { name: null, bundleId: null, processName: null }
}

解決方法：

ターミナル検出が失敗した場合、手動でターミナルタイプを指定できます：

{
  "terminal": "iterm2"
}

---

設定とトラブルシューティング

設定ファイルはどこにありますか？どのように変更しますか？

設定ファイルパス：~/.config/opencode/kdco-notify.json

完全な設定例：

{
  "notifyChildSessions": false,
  "sounds": {
    "idle": "Glass",
    "error": "Basso",
    "permission": "Submarine",
    "question": "Submarine"
  },
  "quietHours": {
    "enabled": true,
    "start": "22:00",
    "end": "08:00"
  },
  "terminal": "ghostty"
}

設定変更手順：

1. ターミナルを開き、設定ファイルを編集：

   # macOS/Linux
   nano ~/.config/opencode/kdco-notify.json
   
   # Windows
   notepad %USERPROFILE%\.config\opencode\kdco-notify.json

2. 設定項目を変更（上記の例を参照）

3. ファイルを保存、設定は自動的に反映（再起動不要）

設定ファイルが破損した場合はどうなりますか？

プラグインはデフォルト設定を使用し、エラーをサイレントに処理します。

エラー処理ロジック（notify.ts:110-113）：

} catch {
  // Config doesn't exist or is invalid, use defaults
  return DEFAULT_CONFIG
}

解決方法：

設定ファイルが破損した場合（JSON フォーマットエラー）、プラグインはデフォルト設定にフォールバックします。修復手順：

1. 破損した設定ファイルを削除：

   rm ~/.config/opencode/kdco-notify.json

2. プラグインはデフォルト設定で動作を継続

3. カスタム設定が必要な場合は、設定ファイルを再作成

---

このレッスンのまとめ

このレッスンでは、ユーザーが最も気になるよくある質問に回答しました：

• パフォーマンスへの影響：プラグインは AI コンテキストを増加させず、リソース消費は極めて少量（CPU ほぼ 0、メモリ < 5 MB）
• プライバシーセキュリティ：完全にローカルで動作、データのアップロードなし、必要最小限のメタデータのみ読み取り
• 通知戦略：スマートフィルタリング機構（親セッションのみ通知、macOS ターミナルフォーカス時の抑制、サイレント時間帯）
• プラグイン互換性：他のプラグインと競合なし、3 大プラットフォームをサポートするが機能に差異あり
• ターミナルサポート：37 以上のターミナルをサポート、自動検出失敗時も正常に動作

---

次のレッスンの予告

次のレッスンでは イベントタイプの説明 を学びます。

学べること：

• プラグインが監視する 4 種類の OpenCode イベントタイプ
• 各イベントのトリガータイミングと通知内容
• イベントのフィルタリングルール（親セッションチェック、サイレント時間帯、ターミナルフォーカス）
• 異なるプラットフォームでのイベント処理の差異

---

付録：ソースコード参照

クリックしてソースコードの場所を表示

更新日：2026-01-27

機能	ファイルパス	行番号
プラグイン起動と設定読み込み	src/notify.ts	357-364
イベント監視ロジック	src/notify.ts	372-400
親セッションチェック	src/notify.ts	256-259
サイレント時間帯チェック	src/notify.ts	262
ターミナルフォーカス検出	src/notify.ts	265
設定ファイル読み込み	src/notify.ts	90-114
ターミナル情報検出	src/notify.ts	145-176
デフォルト設定定義	src/notify.ts	56-68

主要な定数：

• DEFAULT_CONFIG：デフォルト設定（親セッションのみ通知、Glass/Basso/Submarine サウンド、サイレント時間帯はデフォルトで無効）

主要な関数：

• loadConfig()：ユーザー設定を読み込みデフォルト値とマージ
• detectTerminalInfo()：ターミナル情報を検出しキャッシュ
• isQuietHours()：現在時刻がサイレント時間帯かどうかをチェック
• isTerminalFocused()：ターミナルがフォアグラウンドウィンドウかどうかをチェック（macOS）
• isParentSession()：セッションが親セッションかどうかをチェック