高度な使い方：設定テクニックとベストプラクティス

何を学べるか

• デフォルトで親セッションのみ通知する理由を理解し、通知のノイズを減らす
• macOS の通知サウンドをカスタマイズして、イベントの種類を区別する
• ターミナルタイプを手動で指定し、自動検出の問題を解決する
• 一時的なサイレントモードを設定して、会议や集中タイム中に邪魔されないようにする
• 通知戦略を最適化して、適時性と干扰のバランスを取る

現在の困境

通知プラグインは便利ですが、デフォルト設定が必ずしも所有人的仕事スタイルに合わない場合があります：

• すべての AI サブタスクを追跡したいが、デフォルトでは親セッションのみ通知される
• マイナーなターミナルを使用して、自動検出が失敗する
• 会議中に一時的にサイレントにしたいが、毎回設定ファイルを変更したくない
• 異なるタイプのイベントに同じサウンドが使用されており、タスクの完了とエラーの区別がつかない

いつ使うか

プラグインの基本的な使い方をすでに理解し、自分のワークフローに合わせて通知体験を最適化したい場合。

---

コアコンセプト

通知プラグインのデフォルト設定は慎重に設計されていますが、設定ファイルで動作を調整できます。コア原则は：

ノイズを減らし、価値を高める

• 親セッションフィルタリング：メintasksのみ通知し、AI 内部のサブタスクを無視する
• フォーカス感知：ターミナルがアクティブのときは通知せず、重複するリマインダーを避ける
• バッチ通知：複数のタスクが同時に完了した場合、通知をマージする

ヒント

すべての設定項目は設定リファレンスに詳細說明があります。このコースでは、実際の使用テクニックとベストプラクティスに焦点を当てます。

---

🎒 始める前の準備

クイックスタートを完了し、最初の通知の受信に正常に設定していることを確認してください。

---

跟我做（ステップバイステップ）

ステップ 1：親セッションフィルタリングを理解する

なぜ

OpenCode セッションはツリー構造です：1つの親セッションには複数のサブセッションがあります。デフォルトでは、プラグインは親セッションの完了のみを通知し、サブタスクの通知ノイズを避けます。

設定を確認

設定ファイルを編集します：

# macOS/Linux
~/.config/opencode/kdco-notify.json

# Windows
%APPDATA%\opencode\kdco-notify.json

{
  "notifyChildSessions": false  // ← デフォルトは false
}

確認すべきこと：

• notifyChildSessions: false はルートセッションのみを通知することを意味する
• AI 内部で実行されるサブツールの呼び出しは通知をトリガーしない

サブセッション通知を有効にする場合

各サブタスクを追跡する必要がある場合（デバッグマルチステップワークフローなど）は、true に設定します：

{
  "notifyChildSessions": true  // ← 有効にすると、各サブタスクが通知される
}

注意

サブセッション通知を有効にすると、通知頻度が大幅に増加するため、慎重に使用することをお勧めします。

---

ステップ 2：macOS の通知サウンドをカスタマイズする

なぜ

異なるタイプのイベントに異なるサウンドを使用することで、通知を見なくても何が起こったかを知ることができます。

利用可能なサウンドを確認

macOS システムは 14 のビルトインサウンドを提供します：

サウンド名	適用シナリオ	スタイル
Glass	タスク完了（デフォルト）	クリア
Basso	エラー（デフォルト）	低音
Submarine	権限リクエスト（デフォルト）	ソフト
Bottle	特別なイベント	軽快
Ping	一般リマインダー	シンプル
Pop	リラックスイベント	活発
Purr	成功イベント	やさしい
Blow	警告	緊急
Funk	特別なマーク	ユニーク
Frog	リマインダー	大きい
Hero	重要なイベント	壮大
Morse	通知	リズム感
Sosumi	システムプロンプト	クラシック
Tink	完了	軽快

サウンドをカスタマイズ

設定の sounds セクションを編集します：

{
  "sounds": {
    "idle": "Ping",        // タスク完了
    "error": "Blow",      // エラー（より緊急）
    "permission": "Pop",   // 権限リクエスト（より軽快）
    "question": "Tink"    // 質問リクエスト（オプション、デフォルトでは permission サウンドを使用）
  }
}

確認すべきこと：

• 変更後、異なるタイプのイベントが対応するサウンドを再生する
• sounds.question が設定されていない場合、sounds.permission のサウンドが使用される

ヒント

サウンドは macOS でのみ機能します。Windows と Linux はシステムのデフォルト通知サウンドを使用します。

---

ステップ 3：ターミナルタイプを手動で指定する

なぜ

detect-terminal ライブラリは 37+ ターミナルをサポートしていますが、マイナーなターミナルやカスタムビルドバージョンは認識されない場合があります。

現在検出されたターミナルを確認する

検出結果を直接確認することはできませんが、ログから判断できます：

# OpenCode UI にプラグインの起動ログが表示される

「Terminal detection failed」や通知がフォーカスされないなどのメッセージが表示された場合、手動で指定する必要があるかもしれません。

ターミナルを手動で指定

設定に terminal フィールドを追加します：

{
  "terminal": "wezterm"  // ターミナル名の小文字を使用
}

サポートされているターミナル名

一般的なターミナル名（大文字小文字を区別しない）：

ターミナル	設定値
Ghostty	"ghostty"
Kitty	"kitty"
iTerm2	"iterm" または "iterm2"
WezTerm	"wezterm"
Alacritty	"alacritty"
macOS Terminal	"terminal" または "apple_terminal"
Hyper	"hyper"
VS Code ターミナル	"code" または "code-insiders"

確認すべきこと：

• 手動指定後、macOS のフォーカス検出とクリックフォーカス機能が正常に動作する
• 指定が無効な場合、プラグインは静かに失敗し、自動検出にフォールバックする

---

ステップ 4：一時的なサイレント通知

なぜ

会議、コードレビュー、または集中タイム中、一時的に通知を受信したくない場合があります。

サイレントタイムを使用

毎日固定されたタイム（夜間など）で打扰を受けたくない場合は、サイレントタイムを設定します：

{
  "quietHours": {
    "enabled": true,
    "start": "22:00",  // 午後 10 時
    "end": "08:00"     // 翌朝 8 時
  }
}

深夜跨ぎのサポート

サイレントタイムは深夜を跨ぐことができます（22:00-08:00）：

{
  "quietHours": {
    "enabled": true,
    "start": "22:00",
    "end": "08:00"     // 22:00 - 翌 08:00
  }
}

確認すべきこと：

• サイレントタイム内に、すべてのイベントが通知を送信しない
• タイム外は通常の通知に戻る

ヒント

時間形式は HH:MM（24時間制）である必要があります（例：「22:30」）。

---

ステップ 5：通知戦略のバランスを取る

なぜ

デフォルト設定はすでに最適化されていますが、ワークフローに合わせて調整する必要がある場合があります。

デフォルト戦略の概要

設定項目	デフォルト値	効果
notifyChildSessions	false	親セッションのみ通知
quietHours.enabled	false	サイレントタイムを有効化しない

ヒント

フォーカス検出機能（ターミナルがアクティブのときは通知しない）はハードコードされており、設定で無効にすることはできません。

推奨設定の組み合わせ

シナリオ 1：最小干扰を追求する（デフォルト）

{
  "notifyChildSessions": false
}

シナリオ 2：すべてのタスクを追跡する

{
  "notifyChildSessions": true
}

注意

これにより通知頻度が大幅に増加するため、細かい粒度の監視が必要なシナリオに適しています。

シナリオ 3：夜間サイレント

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

確認すべきこと：

• 異なるシナリオに応じて、通知動作に大きな違いがある
• 徐々に調整して自分に最適な設定を見つける

---

チェックポイント ✅

設定を完了したら、以下の内容を確認します：

チェック項目	確認方法
親セッションフィルタリング	サブタスク付きの AI タスクをトリガーし、「Ready for review」通知を 1 つだけ受信する
サウンドのカスタマイズ	タスク完了、エラー、権限リクエストをそれぞれトリガーし、異なるサウンドを聞く
ターミナルオーバーライド	macOS で通知をクリックし、ターミナルウィンドウが正しく前面に表示される
サイレントタイム	サイレントタイム内にイベントをトリガーし、通知を受信しない

---

踩坑提醒（トラブルシューティング）

設定変更が反映されない

問題：設定ファイルを編集したが、通知動作に変化がない。

原因：OpenCode はプラグインまたは OpenCode 自体を再起動する必要がある場合がある。

解決：OpenCode CLI または OpenCode UI を再起動します。

---

サウンドが再生されない

問題：カスタムサウンドを設定したが、デフォルトサウンドのまま。

原因：

• サウンド名のスペルが間違っている
• macOS プラットフォームではない

解決：

• サウンド名がサポートリストにあることを確認（大文字小文字を区別）
• macOS を使用していることを確認

---

ターミナルオーバーライドが無効

問題：terminal フィールドを設定したが、通知をクリックしてもフォーカスされない。

原因：

• ターミナル名が間違っている
• ターミナルプロセス名が設定値と一致しない

解決：

• 小文字の名前を試す
• サポートされているターミナル リストを確認

---

本课小结（今节课のまとめ）

今节课では、opencode-notify の高度な使い方とベストプラクティスを学びました：

• 親セッションフィルタリング：デフォルトでルートセッションのみを通知し、サブタスクのノイズを避ける
• サウンドのカスタマイズ：macOS では 14 のサウンドをカスタマイズでき、イベントの種類を区別できる
• ターミナルオーバーライド：ターミナルタイプを手動で指定し、自動検出の問題を解決する
• 一時的なサイレント：quietHours でサイレントタイムを設定する
• 戦略のバランス：ワークフローに合わせて設定を調整し、適時性と干扰のバランスを取る

コア原则：ノイズを減らし、価値を高める。デフォルト設定はすでに最適化されており、ほとんどの場合、変更は必要ありません。

---

下一课预告（次の授業予告）

次の授業では**トラブルシューティング**を学びます。

学べる内容：

• 通知が表示されない場合の対処法
• フォーカス検出の失效をどのように調査するか
• 一般的なエラーメッセージの解釈
• プラットフォーム固有の問題の解決策

---

附录：源码参考（付録：ソースコードリファレンス）

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

更新時間：2026-01-27

機能	ファイルパス	行番号
親セッション検出	src/notify.ts	205-214
設定 Schema	src/notify.ts	30-68
デフォルト設定	src/notify.ts	56-68
macOS サウンドリスト	README.md	81

重要な定数：

• DEFAULT_CONFIG：デフォルト設定値
• TERMINAL_PROCESS_NAMES：ターミナル名から macOS プロセス名へのマッピングテーブル

重要な関数：

• isParentSession()：セッションが親セッションかどうかを判断
• loadConfig()：ユーザー設定をロードしてマージ