macOS プラットフォーム機能

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

✅ インテリジェントなフォーカス検出を設定し、ターミナルを見ているかどうかをプラグインに認識させる
✅ 通知クリックでターミナルウィンドウに自動フォーカス
✅ 異なるイベントに異なる通知サウンドをカスタマイズ
✅ macOS プラットフォーム固有の利点と制限を理解

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

OpenCode を使用中、頻繁にウィンドウを切り替えていませんか？AI がバックグラウンドでタスクを実行中、ブラウザに切り替えて調べ物をし、数十秒ごとに戻って確認する日々——タスクは完了した？エラーが発生した？それとも入力待ち？

ネイティブのデスクトップ通知があれば便利ですよね。WeChat のメッセージを受け取るように、AI がタスクを完了したり、あなたを必要としたりした時に通知してくれれば。

こんな時に使おう

macOS で OpenCode を使用している - 本レッスンの内容は macOS 専用です
ワークフローを最適化したい - 頻繁なウィンドウ切り替えで AI の状態を確認するのを避けたい
より良い通知体験が欲しい - macOS ネイティブ通知の利点を活用したい

なぜ macOS はより強力なのか？

macOS プラットフォームは完全な通知機能を提供します：フォーカス検出、クリックフォーカス、カスタムサウンド。Windows と Linux は現在、基本的なネイティブ通知機能のみをサポートしています。

🎒 始める前の準備

始める前に、以下を完了していることを確認してください：

前提条件

[ ] クイックスタートチュートリアルを完了済み
[ ] プラグインがインストールされ、正常に動作している
[ ] macOS システムを使用している

基本コンセプト

macOS プラットフォームの完全な通知体験は、3つの主要な機能に基づいています：

1. インテリジェントなフォーカス検出

プラグインは、現在ターミナルウィンドウを見ているかどうかを認識します。AI の出力を確認中であれば、通知で邪魔することはありません。他のアプリに切り替えた時のみ、通知が送信されます。

実装原理：macOS の osascript システムサービスを通じて現在のフォアグラウンドアプリのプロセス名を照会し、使用しているターミナルのプロセス名と比較します。

2. 通知クリックでターミナルにフォーカス

通知を受け取った後、通知カードを直接クリックすると、ターミナルウィンドウが自動的に最前面に表示されます。すぐに作業状態に戻れます。

実装原理：macOS Notification Center は activate オプションをサポートしており、アプリの Bundle ID を渡すことでクリックフォーカスを実現します。

3. カスタムサウンド

異なるタイプのイベントに異なるサウンドを設定：タスク完了には軽快なサウンド、エラーには低いサウンドを使用することで、通知を見なくても大まかな状況を把握できます。

実装原理：macOS システム内蔵の14種類の標準サウンド（Glass、Basso、Submarine など）を利用し、設定ファイルの sounds フィールドで指定します。

3つの機能の連携

フォーカス検出で邪魔を回避 → 通知クリックで素早く復帰 → サウンドでイベントタイプを素早く識別

手順

ステップ1：自動検出されたターミナルを確認

プラグインは起動時に使用しているターミナルエミュレーターを自動検出します。正しく認識されているか確認しましょう。

なぜ

プラグインがフォーカス検出とクリックフォーカス機能を実現するには、ターミナルが何かを知る必要があります。

操作

OpenCode の設定ディレクトリを開きます：
bash
```
ls ~/.config/opencode/
```
すでに kdco-notify.json 設定ファイルを作成している場合、terminal フィールドがあるか確認します：
bash
```
cat ~/.config/opencode/kdco-notify.json
```
設定ファイルに terminal フィールドがない場合、プラグインは自動検出を使用しています。

期待される結果

設定ファイルに terminal フィールドがない場合、プラグインは自動検出します。サポートされているターミナル：

一般的なターミナル：Ghostty、Kitty、iTerm2、WezTerm、Alacritty
システムターミナル：macOS 標準の Terminal.app
その他のターミナル：Hyper、Warp、VS Code 統合ターミナルなど

37以上のターミナルをサポート

プラグインは detect-terminal ライブラリを使用し、37以上のターミナルエミュレーターをサポートしています。よく使われるリストにないターミナルでも、自動認識を試みます。

ステップ2：カスタムサウンドを設定

macOS は14種類の内蔵サウンドを提供しており、異なるイベントに異なるサウンドを割り当てることができます。

なぜ

異なるサウンドにより、通知を見なくても何が起きたかを大まかに把握できます：タスク完了かエラーか、AI が待機中か単にタスクを完了しただけか。

操作

設定ファイルを開くか作成します：
bash
```
nano ~/.config/opencode/kdco-notify.json
```
sounds 設定を追加または変更します：

json

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

保存して終了（Ctrl+O、Enter、Ctrl+X）

期待される結果

設定ファイルの sounds フィールドには4つのオプションがあります：

フィールド	用途	デフォルト値	推奨設定
`idle`	タスク完了サウンド	Glass	Glass（軽快）
`error`	エラー通知サウンド	Basso	Basso（低音）
`permission`	権限リクエストサウンド	Submarine	Submarine（アラート）
`question`	AI 質問サウンド（オプション）	permission	Purr（柔らか）

推奨の組み合わせ

このデフォルトの組み合わせは直感的です：完了には軽快なサウンド、エラーには警告サウンド、権限リクエストにはアラートサウンド。

ステップ3：利用可能なサウンドリストを確認

macOS には14種類の内蔵サウンドがあり、自由に組み合わせることができます。

なぜ

利用可能なすべてのサウンドを知ることで、自分の作業習慣に最適な組み合わせを見つけられます。

利用可能なサウンド

サウンド名	聴感の特徴	適用シーン
Glass	軽快、クリア	タスク完了
Basso	低音、警告	エラー通知
Submarine	アラート、柔らか	権限リクエスト
Blow	力強い	重要なイベント
Bottle	クリア	サブタスク完了
Frog	リラックス	カジュアルなリマインダー
Funk	リズミカル	複数タスク完了
Hero	壮大	マイルストーン達成
Morse	モールス信号	デバッグ関連
Ping	クリア	軽量リマインダー
Pop	短い	クイックタスク
Purr	柔らか	邪魔しないリマインダー
Sosumi	ユニーク	特別なイベント
Tink	明るい	小さなタスク完了

サウンドで状況を把握

設定完了後、異なるサウンドの組み合わせを試して、ワークフローに最適な設定を見つけてください。

ステップ4：クリックフォーカス機能をテスト

通知をクリックすると、ターミナルウィンドウが自動的に最前面に表示されます。これは macOS 固有の機能です。

なぜ

通知を受け取った時、手動でターミナルに切り替えてウィンドウを探す必要がありません。通知をクリックするだけで作業状態に直接戻れます。

操作

OpenCode が実行中で、AI タスクを開始していることを確認
他のアプリ（ブラウザなど）に切り替え
AI タスクの完了を待つと、「Ready for review」通知を受け取ります
通知カードをクリック

期待される結果

通知が消える
ターミナルウィンドウが自動的に最前面に表示され、フォーカスを取得
すぐに AI の出力を確認できる

フォーカスの仕組み

プラグインは osascript を通じてターミナルアプリの Bundle ID を動的に取得し、通知送信時に activate オプションを渡します。macOS Notification Center がこのオプションを受け取ると、通知クリック時に対応するアプリを自動的にアクティブにします。

ステップ5：フォーカス検出機能を確認

ターミナルを見ている時は、通知を受け取りません。これにより重複したリマインダーを回避します。

なぜ

すでにターミナルを見ているなら、通知は不要です。他のアプリに切り替えた時のみ、通知に意味があります。

操作

OpenCode を開き、AI タスクを開始
ターミナルウィンドウをフォアグラウンドに保つ（切り替えない）
タスクの完了を待つ

期待される結果

「Ready for review」通知を受け取らない
ターミナル内にタスク完了が表示される

次に試してみましょう：

別の AI タスクを開始
ブラウザや他のアプリに切り替え
タスクの完了を待つ

期待される結果

「Ready for review」通知を受け取る
設定したサウンドが再生される（デフォルトは Glass）

フォーカス検出のインテリジェンス

プラグインは、ターミナルを見ている時と見ていない時を認識します。これにより、重要なリマインダーを見逃すことなく、重複した通知に邪魔されることもありません。

チェックポイント ✅

設定チェック

[ ] 設定ファイル ~/.config/opencode/kdco-notify.json が存在する
[ ] sounds フィールドが設定されている（少なくとも idle、error、permission を含む）
[ ] terminal フィールドが設定されていない（自動検出を使用）

機能チェック

[ ] AI タスク完了後に通知を受け取れる
[ ] 通知クリック後にターミナルウィンドウが最前面に表示される
[ ] ターミナルウィンドウがフォアグラウンドの時、重複通知を受け取らない
[ ] 異なるイベントタイプで異なるサウンドが再生される

フォーカス検出が機能しない？

通知クリック後にターミナルが最前面に表示されない場合、以下が原因の可能性があります：

ターミナルアプリが正しく認識されていない - 設定ファイルの terminal フィールドを確認
Bundle ID の取得に失敗 - OpenCode ログのエラーメッセージを確認

よくある問題と解決策

サウンドが再生されない

問題：サウンドを設定したが、通知時に音が出ない

考えられる原因：

システム音量が低すぎるかミュートになっている
macOS システム環境設定で通知サウンドが無効になっている

解決方法：

システム音量と通知設定を確認
「システム設定 → 通知 → OpenCode」を開き、サウンドが有効になっていることを確認

通知クリックでフォーカスしない

問題：通知クリック後、ターミナルウィンドウが最前面に表示されない

考えられる原因：

ターミナルアプリが自動検出されていない
Bundle ID の取得に失敗

解決方法：

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

json

{
  "terminal": "ghostty"  // または他のターミナル名
}

ターミナルアプリ名が正しいことを確認（大文字小文字を区別）

フォーカス検出が機能しない

問題：ターミナルがフォアグラウンドでも、通知を受け取ってしまう

考えられる原因：

ターミナルプロセス名の検出に失敗
ターミナルアプリが自動検出リストにない

解決方法：

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

json

{
  "terminal": "ghostty"  // または他のターミナル名
}

ターミナルアプリ名が正しいことを確認（大文字小文字を区別）
ログを確認し、ターミナルが正しく認識されているか確認

このレッスンのまとめ

macOS プラットフォームは完全な通知体験を提供します：

機能	用途	プラットフォームサポート
ネイティブ通知	システムレベルの通知を表示	✅ macOS ✅ Windows ✅ Linux
カスタムサウンド	異なるイベントに異なるサウンド	✅ macOS
フォーカス検出	重複通知を回避	✅ macOS
クリックフォーカス	素早く作業に復帰	✅ macOS

コア設定：

json

{
  "sounds": {
    "idle": "Glass",       // タスク完了
    "error": "Basso",      // エラー
    "permission": "Submarine"  // 権限リクエスト
  }
}

ワークフロー：

AI がタスクを完了 → 通知を送信 → Glass サウンドを再生
ブラウザで作業中 → 通知を受け取る → クリック
ターミナルが自動的に最前面に → AI の出力を確認

次のレッスン予告

次のレッスンでは Windows プラットフォーム機能 を学びます。
学べること：
Windows プラットフォームでサポートされている機能
macOS との違い
Windows での通知設定方法

付録：ソースコード参照

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

更新日：2026-01-27

機能	ファイルパス	行番号
フォーカス検出	`src/notify.ts`	166-175
クリックフォーカス	`src/notify.ts`	238-240
Bundle ID 取得	`src/notify.ts`	135-137
フォアグラウンドアプリ検出	`src/notify.ts`	139-143
ターミナル名マッピング	`src/notify.ts`	71-84
デフォルトサウンド設定	`src/notify.ts`	59-61
macOS サウンドリスト	`README.md`	81
プラットフォーム機能比較表	`README.md`	54-62

主要な定数：

TERMINAL_PROCESS_NAMES (行 71-84)：ターミナル名から macOS プロセス名へのマッピングテーブル
- ghostty → "Ghostty"
- kitty → "kitty"
- iterm / iterm2 → "iTerm2"
- wezterm → "WezTerm"
- alacritty → "Alacritty"
- terminal / apple_terminal → "Terminal"
- hyper → "Hyper"
- warp → "Warp"
- vscode → "Code"
- vscode-insiders → "Code - Insiders"

デフォルト設定：

sounds.idle = "Glass"：タスク完了サウンド
sounds.error = "Basso"：エラー通知サウンド
sounds.permission = "Submarine"：権限リクエストサウンド

主要な関数：

isTerminalFocused(terminalInfo) (行 166-175)：ターミナルがフォアグラウンドアプリかどうかを検出
- osascript を使用してフォアグラウンドアプリのプロセス名を取得
- ターミナルの processName と比較（大文字小文字を区別しない）
- macOS プラットフォームでのみ有効
getBundleId(appName) (行 135-137)：アプリの Bundle ID を動的に取得
- osascript を使用して照会
- Bundle ID は通知クリックフォーカス機能に使用
getFrontmostApp() (行 139-143)：現在のフォアグラウンドアプリを取得
- osascript を使用して System Events に照会
- フォアグラウンドアプリのプロセス名を返す
sendNotification(options) (行 227-243)：通知を送信
- macOS 機能：プラットフォームが darwin で terminalInfo.bundleId がある場合、activate オプションを設定してクリックフォーカスを実現

macOS プラットフォーム機能 ​

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

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

こんな時に使おう ​

🎒 始める前の準備 ​

基本コンセプト ​

1. インテリジェントなフォーカス検出 ​

2. 通知クリックでターミナルにフォーカス ​

3. カスタムサウンド ​

手順 ​

ステップ1：自動検出されたターミナルを確認 ​

ステップ2：カスタムサウンドを設定 ​

ステップ3：利用可能なサウンドリストを確認 ​

ステップ4：クリックフォーカス機能をテスト ​

ステップ5：フォーカス検出機能を確認 ​

チェックポイント ✅ ​

設定チェック ​

機能チェック ​

よくある問題と解決策 ​

サウンドが再生されない ​

通知クリックでフォーカスしない ​

フォーカス検出が機能しない ​

このレッスンのまとめ ​

次のレッスン予告 ​

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

macOS プラットフォーム機能

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

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

こんな時に使おう

🎒 始める前の準備

基本コンセプト

1. インテリジェントなフォーカス検出

2. 通知クリックでターミナルにフォーカス

3. カスタムサウンド

手順

ステップ1：自動検出されたターミナルを確認

ステップ2：カスタムサウンドを設定

ステップ3：利用可能なサウンドリストを確認

ステップ4：クリックフォーカス機能をテスト

ステップ5：フォーカス検出機能を確認

チェックポイント ✅

設定チェック

機能チェック

よくある問題と解決策

サウンドが再生されない

通知クリックでフォーカスしない

フォーカス検出が機能しない

このレッスンのまとめ

次のレッスン予告

付録：ソースコード参照