問題4：サウンドが再生されない（macOSのみ）

症状：通知は正常に表示されるが、サウンドが再生されない。

4.1 サウンド名が正しいか確認

サポートされているmacOSサウンド：

サウンド名	説明	サウンド名	説明
Basso	低音	Blow	吹く音
Bottle	ボトル音	Frog	カエル音
Funk	ファンク	Glass	ガラス音（デフォルトのタスク完了）
Hero	ヒーロー	Morse	モールス信号
Ping	ピン音	Pop	ポップ音
Purr	ゴロゴロ音	Sosumi	Sosumi
Submarine	潜水艦（デフォルトの権限リクエスト）	Tink	チン音

設定例：

json

{
  "sounds": {
    "idle": "Glass",
    "error": "Basso",
    "permission": "Submarine",
    "question": "Ping"
  }
}

4.2 システム音量設定を確認

診断手順：

bash

# システム設定 → サウンド → 出力音量を開く
# 音量がミュートされていないこと、適切な音量であることを確認

4.3 他のプラットフォームはカスタムサウンドをサポートしていない

症状：WindowsまたはLinuxユーザーで、サウンドを設定したが音が出ない。

原因：カスタムサウンドはmacOS専用機能で、WindowsとLinuxはサポートしていません。

解決方法：WindowsとLinuxユーザーは通知を受け取りますが、サウンドはシステムのデフォルト設定で制御され、プラグイン設定では変更できません。

Windows/Linuxのサウンド

WindowsとLinuxの通知サウンドはシステム設定で制御されます：

Windows：設定 → システム → 通知 → 通知サウンドを選択
Linux：デスクトップ環境設定 → 通知 → サウンド

問題5：通知をクリックしてもフォーカスされない（macOSのみ）

症状：通知をクリックした後、ターミナルウィンドウが前面に表示されない。

5.1 Bundle IDが正常に取得されているか確認

原因：通知クリックフォーカス機能は、ターミナルのBundle ID（例：com.ghostty.Ghostty）を取得する必要があります。取得に失敗すると、フォーカスできません。

診断手順：

プラグインは起動時に自動的にターミナルを検出し、Bundle IDを取得します。失敗した場合、通知クリックフォーカス機能は使用できません。

よくある原因：

ターミナルがマッピングテーブルにない（カスタムターミナルなど）
osascript の実行に失敗（macOS権限の問題）

解決方法：ターミナルタイプを手動で指定（2.2節を参照）。

5.2 システムアクセシビリティ権限を確認

原因：macOSでは、他のアプリのウィンドウを制御するために「アクセシビリティ」権限が必要です。

診断手順：

bash

# システム設定 → プライバシーとセキュリティ → アクセシビリティを開く
# ターミナルアプリにアクセシビリティ権限があることを確認

期待される結果：ターミナルアプリ（Ghostty、iTerm2など）がアクセシビリティリストに表示され、スイッチがオンになっている。

問題6：プラットフォームの機能差異

症状：macOSからWindows/Linuxに切り替えたら、一部の機能が使えなくなった。

6.1 機能比較表

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

説明：

Windows/Linux：基本的な通知機能のみサポート、高度な機能（フォーカス検出、クリックフォーカス、カスタムサウンド）は使用不可
macOS：すべての機能をサポート

6.2 設定ファイルのクロスプラットフォーム互換性

問題：macOSで sounds を設定したが、Windowsに切り替えたらサウンドが機能しない。

原因：sounds 設定はmacOSでのみ有効です。

解決方法：設定ファイルはクロスプラットフォームで使用でき、プラグインはサポートされていない設定項目を自動的に無視します。sounds フィールドを削除する必要はなく、Windows/Linuxは静かに無視します。

ベストプラクティス

同じ設定ファイルを複数のプラットフォーム間で使用し、プラグインがプラットフォームの違いを自動的に処理します。プラットフォームごとに個別の設定ファイルを作成する必要はありません。

まとめ

opencode-notifyのトラブルシューティングは、以下の6つの問題カテゴリにまとめられます：

通知が表示されない：プラグインのインストール、macOS通知権限、サイレント時間帯、ターミナルフォーカス、サブセッションフィルタリング、プラグインが無効になっていないかを確認
フォーカス検出が機能しない（macOS）：ターミナルが正しく検出されているか確認、または手動でターミナルタイプを指定
設定が反映されない：JSONフォーマット、設定ファイルパス、OpenCodeの再起動を確認
サウンドが再生されない（macOS）：サウンド名が正しいか確認、サウンドはmacOSでのみサポートされていることを確認
通知をクリックしてもフォーカスされない（macOS）：Bundle IDの取得とアクセシビリティ権限を確認
プラットフォームの機能差異：Windows/Linuxは基本的な通知のみサポート、高度な機能はmacOSでのみ使用可能

クイック診断チェックリスト：

□ プラグインが正しくインストールされているか？
□ macOS通知権限が許可されているか？
□ サイレント時間帯が有効になっているか？
□ ターミナルがフォーカスされているか？
□ サブセッションフィルタリングが有効になっているか？
□ 設定ファイルのJSONフォーマットが正しいか？
□ 設定ファイルのパスが正しいか？
□ OpenCodeを再起動したか？
□ サウンド名がサポートリストにあるか（macOSのみ）？
□ Bundle IDが正常に取得されているか（macOSのみ）？
□ システム音量が正常か？

次のレッスン予告

次のレッスンでは よくある質問 を学習します。
学べること：
opencode-notifyが会話コンテキストのオーバーヘッドを増やすか
大量の通知が送られてくるか
通知を一時的に無効にする方法
パフォーマンスへの影響とプライバシーセキュリティの問題

付録：ソースコード参照

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

更新日：2026-01-27

機能	ファイルパス	行番号
設定の読み込みとエラー処理	`src/notify.ts`	90-114
ターミナル検出	`src/notify.ts`	145-164
macOS osascript実行	`src/notify.ts`	120-133
ターミナルフォーカス検出	`src/notify.ts`	166-175
サイレント時間帯チェック	`src/notify.ts`	181-199
親セッション検出	`src/notify.ts`	205-214
通知送信	`src/notify.ts`	227-243
デフォルト設定	`src/notify.ts`	56-68
ターミナルプロセス名マッピング	`src/notify.ts`	71-84
タスク完了処理	`src/notify.ts`	249-284
エラー通知処理	`src/notify.ts`	286-313
権限リクエスト処理	`src/notify.ts`	315-334
質問処理	`src/notify.ts`	336-351

主要な定数：

DEFAULT_CONFIG：デフォルト設定（56-68行目）
- notifyChildSessions: false：デフォルトではサブセッションを通知しない
- sounds.idle: "Glass"：タスク完了サウンド
- sounds.error: "Basso"：エラーサウンド
- sounds.permission: "Submarine"：権限リクエストサウンド
- quietHours.start: "22:00"、quietHours.end: "08:00"：デフォルトのサイレント時間帯
TERMINAL_PROCESS_NAMES：ターミナル名からmacOSプロセス名へのマッピング（71-84行目）

主要な関数：

loadConfig()：設定ファイルとデフォルト設定を読み込んでマージ、設定ファイルが存在しないか無効な場合はデフォルト値を使用
detectTerminalInfo()：ターミナル情報（名前、Bundle ID、プロセス名）を検出
isTerminalFocused()：ターミナルが現在のフォアグラウンドアプリかどうかをチェック（macOS）
isQuietHours()：現在時刻がサイレント時間帯内かどうかをチェック
isParentSession()：セッションが親セッションかどうかをチェック
sendNotification()：ネイティブ通知を送信、macOSクリックフォーカスをサポート
runOsascript()：AppleScriptを実行（macOS）、失敗時はnullを返す
getBundleId()：アプリのBundle IDを取得（macOS）

ビジネスルール：

BR-1-1：デフォルトでは親セッションのみ通知、サブセッションは通知しない（notify.ts:256-259）
BR-1-2：ターミナルがフォーカスされている時は通知を抑制（notify.ts:265）
BR-1-3：サイレント時間帯内は通知を送信しない（notify.ts:262）
BR-1-4：権限リクエストは常に通知、親セッションチェック不要（notify.ts:319）
BR-1-5：質問はフォーカスチェックを行わず、tmuxワークフローをサポート（notify.ts:340）
BR-1-6：macOSは通知クリックでターミナルをフォーカスすることをサポート（notify.ts:238-240）

例外処理：

loadConfig()：設定ファイルが存在しないかJSON解析に失敗した場合、デフォルト設定を使用（notify.ts:110-113）
isParentSession()：セッションクエリに失敗した場合、親セッションと仮定（通知して見逃さない）（notify.ts:210-212）
runOsascript()：osascript実行に失敗した場合はnullを返す（notify.ts:120-132）
handleSessionIdle()：セッション情報の取得に失敗した場合、デフォルトタイトルを使用（notify.ts:274-276）

トラブルシューティング：通知が表示されない、フォーカス検出が機能しないなどの一般的な問題

このチュートリアルで学べること

通知が表示されない原因を素早く特定
macOS通知権限の問題を解決
フォーカス検出が機能しない問題を診断
設定ファイルのフォーマットエラーを修正
プラットフォームごとの機能差異を理解

今あなたが抱えている課題

AIがタスクを完了したのに通知が届かない、または通知をクリックしてもターミナルが前面に表示されない。どこに問題があるのか、どこから診断を始めればよいのかわからない。

こんな時に使おう

プラグインをインストールして初めて使用したが、通知が一切届かない
プラグインやシステムを更新した後、突然通知が機能しなくなった
特定の通知動作を無効にしたいが、設定が反映されていない
macOSからWindows/Linuxに切り替えたら、一部の機能が使えなくなった

基本コンセプト

opencode-notifyのワークフローは比較的シンプルですが、複数の段階が関与しています：OpenCode SDK → イベント監視 → フィルタリングロジック → OS通知。どの段階でも問題が発生すると、通知が表示されなくなる可能性があります。

診断の鍵は各段階を順番にチェックすることで、最も可能性の高い原因から始めます。80%の問題は以下の5つのカテゴリで解決できます：

通知が表示されない - 最も一般的な問題
フォーカス検出が機能しない（macOSのみ）
設定が反映されない - JSONフォーマットまたはパスエラー
サウンドが再生されない（macOSのみ）
プラットフォームの違い - 一部の機能がサポートされていない

問題1：通知が表示されない

これは最も一般的な問題で、6つの原因が考えられます。順番にチェックしてください：

1.1 プラグインが正しくインストールされているか確認

症状：OpenCodeは正常に動作しているが、通知が一度も届かない。

診断手順：

bash

# プラグインがインストールされているか確認
ls ~/.opencode/plugin/kdco-notify

# 存在しない場合は再インストール
ocx add kdco/notify

期待される結果：~/.opencode/plugin/kdco-notify ディレクトリが存在し、package.json や src/notify.ts などのファイルが含まれている。

手動インストールの確認

手動インストールを使用している場合は、以下を確認してください：

依存関係がインストール済み：npm install node-notifier detect-terminal
プラグインファイルが正しい場所にある：~/.opencode/plugin/
OpenCodeを再起動済み（プラグインの変更には再起動が必要）

1.2 macOS通知権限を確認

症状：macOSユーザーのみ、プラグインはインストール済みだが通知が一度も届かない。

原因：macOSでは、ターミナルアプリが通知を送信する権限を明示的に許可する必要があります。

診断手順：

bash

# 1. システム設定を開く
# macOS Ventura以降：システム設定 → 通知と集中モード
# macOS旧バージョン：システム環境設定 → 通知

# 2. ターミナルアプリ（Ghostty、iTerm2、Terminal.appなど）を探す
# 3. 「通知を許可」がオンになっているか確認
# 4. 「ロック画面に表示」と「画面ロック時にバナーを表示」がオンになっているか確認

期待される結果：ターミナルアプリが通知設定に表示され、「通知を許可」スイッチが緑色になっている。

よくある間違い

OpenCode自体は通知設定に表示されません。許可が必要なのはターミナルアプリ（Ghostty、iTerm2、Terminal.appなど）であり、OpenCodeではありません。

1.3 サイレント時間帯設定を確認

症状：特定の時間帯に通知が届かないが、他の時間帯では届く。

原因：設定ファイルでサイレント時間帯が有効になっている。

診断手順：

bash

# 設定ファイルを確認
cat ~/.config/opencode/kdco-notify.json

解決方法：

json

{
  "quietHours": {
    "enabled": false,
    "start": "22:00",
    "end": "08:00"
  }
}

期待される結果：quietHours.enabled が false になっているか、現在時刻がサイレント時間帯外である。

深夜をまたぐサイレント時間帯

サイレント時間帯は深夜をまたぐ設定（22:00-08:00など）をサポートしています。これは正しい動作です。現在時刻が夜10時から翌朝8時の間の場合、通知は抑制されます。

1.4 ターミナルウィンドウのフォーカスを確認

症状：ターミナルを見ている時に通知が届かない。

原因：これは期待される動作であり、バグではありません。フォーカス検出メカニズムは、ターミナルを見ている時に通知を抑制し、重複した通知を避けます。

診断手順：

ターミナルがフォーカスされているか確認：

他のアプリ（ブラウザ、VS Codeなど）に切り替える
AIにタスクを実行させる
タスクの完了を待つ

期待される結果：他のアプリを使用している時に、通知が正常に表示される。

フォーカス検出の説明

フォーカス検出は組み込み動作であり、設定で無効にすることはできません。プラグインはデフォルトでターミナルがフォーカスされている時の通知を抑制し、重複した通知を避けます。これは設計上の期待される動作です。

1.5 サブセッションフィルタリングを確認

症状：AIが複数のサブタスクを実行したが、各サブタスクの通知が届かない。

原因：これは期待される動作です。プラグインはデフォルトで親セッションのみ通知し、サブセッションは通知しません。これにより通知の過剰な送信を防ぎます。

診断手順：

親セッションとサブセッションの理解：

親セッション：あなたが直接AIに実行させたタスク（例：「コードベースを最適化」）
サブセッション：AIが自動的に分割したサブタスク（例：「src/componentsを最適化」、「src/utilsを最適化」）

サブセッション通知が本当に必要な場合：

json

{
  "notifyChildSessions": true
}

期待される結果：各サブセッションが完了するたびに通知が届く。

推奨される方法

複数の並行タスクを監視している場合を除き、notifyChildSessions: false のままにして、親セッションの通知のみを受け取ることをお勧めします。

1.6 設定ファイルが削除または名前変更されていないか確認

症状：以前は通知が届いていたが、突然表示されなくなった。

診断手順：

bash

# 設定ファイルが存在するか確認
ls -la ~/.config/opencode/kdco-notify.json

解決方法：

設定ファイルが削除されたりパスが間違っている場合、プラグインはデフォルト設定を使用します：

設定ファイルを削除してデフォルトに戻す：

bash

# 設定ファイルを削除してデフォルト設定を使用
rm ~/.config/opencode/kdco-notify.json

期待される結果：プラグインが通知の送信を再開する（デフォルト設定を使用）。

問題2：フォーカス検出が機能しない（macOSのみ）

症状：ターミナルを見ている時でも通知が届き、フォーカス検出が機能していないようだ。

2.1 ターミナルが正しく検出されているか確認

原因：プラグインは detect-terminal ライブラリを使用してターミナルを自動識別します。識別に失敗すると、フォーカス検出が機能しません。

診断手順：

bash

# ターミナル検出が正常か確認
node -e "console.log(require('detect-terminal')())"

期待される結果：ターミナル名（ghostty、iterm2 など）が出力される。

出力が空の場合、ターミナル検出に失敗しています。

2.2 ターミナルタイプを手動で指定

自動検出に失敗した場合、手動で指定できます：

json

{
  "terminal": "ghostty"
}

サポートされているターミナル名（小文字）：

ターミナル	名前	ターミナル	名前
Ghostty	`ghostty`	Kitty	`kitty`
iTerm2	`iterm2` または `iterm`	WezTerm	`wezterm`
Alacritty	`alacritty`	macOS Terminal	`terminal` または `apple_terminal`
Hyper	`hyper`	Warp	`warp`
VS Code ターミナル	`vscode`	VS Code Insiders	`vscode-insiders`

プロセス名マッピング

プラグイン内部にはターミナル名からmacOSプロセス名へのマッピングテーブルがあります。terminal を手動で指定する場合は、マッピングテーブル内の名前（71-84行目）を使用してください。

問題3：設定が反映されない

症状：設定ファイルを変更したが、プラグインの動作が変わらない。

3.1 JSONフォーマットが正しいか確認

よくあるエラー：

json

// ❌ エラー：引用符がない
{
  notifyChildSessions: true
}

// ❌ エラー：末尾のカンマ
{
  "notifyChildSessions": true,
}

// ❌ エラー：コメントはサポートされていない
{
  "notifyChildSessions": true
}

正しいフォーマット：

json

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

JSONフォーマットを検証：

bash

# jqを使用してJSONフォーマットを検証
cat ~/.config/opencode/kdco-notify.json | jq '.'

# フォーマットされたJSONが出力されれば正しい
# エラーが出た場合はJSONに問題がある

3.2 設定ファイルのパスを確認

症状：設定ファイルを作成したが、プラグインが読み込んでいないようだ。

正しいパス：

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

診断手順：

bash

# 設定ファイルが存在するか確認
ls -la ~/.config/opencode/kdco-notify.json

# 存在しない場合はディレクトリとファイルを作成
mkdir -p ~/.config/opencode
cat > ~/.config/opencode/kdco-notify.json << 'EOF'
{
  "notifyChildSessions": false
}
EOF

3.3 OpenCodeを再起動

原因：プラグインは起動時に一度設定を読み込むため、変更後は再起動が必要です。

診断手順：

bash

# OpenCodeを完全に再起動
# 1. OpenCodeを終了
# 2. OpenCodeを再起動

問題4：サウンドが再生されない（macOSのみ） ​

4.1 サウンド名が正しいか確認 ​

4.2 システム音量設定を確認 ​

4.3 他のプラットフォームはカスタムサウンドをサポートしていない ​

問題5：通知をクリックしてもフォーカスされない（macOSのみ） ​

5.1 Bundle IDが正常に取得されているか確認 ​

5.2 システムアクセシビリティ権限を確認 ​

問題6：プラットフォームの機能差異 ​

6.1 機能比較表 ​

6.2 設定ファイルのクロスプラットフォーム互換性 ​

まとめ ​

次のレッスン予告 ​

付録：ソースコード参照 ​

トラブルシューティング：通知が表示されない、フォーカス検出が機能しないなどの一般的な問題 ​

このチュートリアルで学べること ​

今あなたが抱えている課題 ​

こんな時に使おう ​

基本コンセプト ​

問題1：通知が表示されない ​

1.1 プラグインが正しくインストールされているか確認 ​

1.2 macOS通知権限を確認 ​

1.3 サイレント時間帯設定を確認 ​

1.4 ターミナルウィンドウのフォーカスを確認 ​

1.5 サブセッションフィルタリングを確認 ​

1.6 設定ファイルが削除または名前変更されていないか確認 ​

問題2：フォーカス検出が機能しない（macOSのみ） ​

2.1 ターミナルが正しく検出されているか確認 ​

2.2 ターミナルタイプを手動で指定 ​

問題3：設定が反映されない ​

3.1 JSONフォーマットが正しいか確認 ​

3.2 設定ファイルのパスを確認 ​

3.3 OpenCodeを再起動 ​

問題4：サウンドが再生されない（macOSのみ）

4.1 サウンド名が正しいか確認

4.2 システム音量設定を確認

4.3 他のプラットフォームはカスタムサウンドをサポートしていない

問題5：通知をクリックしてもフォーカスされない（macOSのみ）

5.1 Bundle IDが正常に取得されているか確認

5.2 システムアクセシビリティ権限を確認

問題6：プラットフォームの機能差異

6.1 機能比較表

6.2 設定ファイルのクロスプラットフォーム互換性

まとめ

次のレッスン予告

付録：ソースコード参照

トラブルシューティング：通知が表示されない、フォーカス検出が機能しないなどの一般的な問題

このチュートリアルで学べること

今あなたが抱えている課題

こんな時に使おう

基本コンセプト

問題1：通知が表示されない

1.1 プラグインが正しくインストールされているか確認

1.2 macOS通知権限を確認

1.3 サイレント時間帯設定を確認

1.4 ターミナルウィンドウのフォーカスを確認

1.5 サブセッションフィルタリングを確認

1.6 設定ファイルが削除または名前変更されていないか確認

問題2：フォーカス検出が機能しない（macOSのみ）

2.1 ターミナルが正しく検出されているか確認

2.2 ターミナルタイプを手動で指定

問題3：設定が反映されない

3.1 JSONフォーマットが正しいか確認

3.2 設定ファイルのパスを確認

3.3 OpenCodeを再起動