Claude Code通知の設定 — ターミナルベルとNotificationフック

Claude Codeが完了時に鳴らす仕組み

Claude Codeはタスクが終わったとき、または権限確認で応答待ちのまま離席していると判断したときに、Notificationイベントを発火します。この仕組みそのものはすべてのターミナルで動きますが、それを画面の外まで知らせる手段は既定では限られています。

デスクトップ通知が既定で届くのはGhostty・Kitty・iTerm2の3つだけです。それ以外のターミナルでは、何も設定しなければ通知は静かに失われます。大きめのリファクタリングを投げて離席したときや、Bashコマンドの実行許可を求められたまま数分放置してしまったときが典型的な発火場面です。この記事では、それ以外のターミナルで通知を受け取る方法と、音やカスタム処理を鳴らすNotification hookの設定をまとめます。

デスクトップ通知が来ないときの直し方

preferredNotifChannelは~/.claude/settings.jsonに書く設定で、既定値は"auto"です。"auto"はiTerm2・Ghostty・Kittyでのみデスクトップ通知を送り、それ以外のターミナルでは何もしません。この既定を変えたい場合は、次のように"terminal_bell"を指定します。

{
  "preferredNotifChannel": "terminal_bell"
}

terminal_bellにすると、対応ターミナルの限定を外れ、どのターミナルでもベル文字による通知が鳴るようになります。値は他に"iterm2"・"iterm2_with_bell"・"kitty"・"ghostty"・"notifications_disabled"も選べます。/config画面ではNotificationsという項目名で同じ設定を変更できます。

デスクトップ通知はSSH経由でも手元のマシンまで届きます。リモートサーバーで作業していても、手元のマシンに通知が出る仕組みです。GhosttyとKittyはOSの通知センターへの転送を追加設定なしで行いますが、iTerm2だけは転送を有効にする作業が要ります。

iTerm2で通知を有効にする

iTerm2でデスクトップ通知を受け取るには、Settings → Profiles → Terminalを開き、「Notification Center Alerts」にチェックを入れます。続けて「Filter Alerts」をクリックし、「Send escape sequence-generated alerts」を有効にします。この2箇所を有効にしないと、iTerm2は通知のためのエスケープシーケンスを受け取っても画面外への転送を行いません。

設定を反映してもまだ通知が来ない場合は、iTerm2自体ではなくOS側の通知権限を確認してください。ターミナルアプリケーションにOSの通知権限が付与されていないと、iTerm2側の設定が正しくてもデスクトップ通知は表示されません。

tmuxの中では追加設定が要る

tmuxの中でClaude Codeを動かしている場合、allow-passthroughを有効にしないと、対応ターミナルを使っていても通知はtmuxに飲み込まれます。tmux固有の設定手順とフルスクリーンレンダリングとの併用についてはClaude Code tmux設定にまとめています。tmux越しでも設定が有効なら、preferredNotifChannelをterminal_bellに切り替える対処はそのまま使えます。

Notification hookで音やカスタム処理を実行する

preferredNotifChannelが対応していないターミナル(WarpやVS Codeの統合ターミナルなど)でも、Notification hookを使えば任意のコマンドを実行できます。組み込みの通知に代わるものではなく、両方が並行して動く仕組みなので、既存の通知設定を変えずに音だけ追加することもできます。

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}

上の例はmacOSでシステムサウンドを鳴らすコマンドです。Linuxではデスクトップ通知コマンド(notify-sendなど)、Windowsでも同様にOS標準の通知コマンドをNotificationイベントに紐づけられます。Slackへの投稿や社内チャットへの転送など、コマンドとして実行できるものであれば何でも組み込めます。Notification以外のイベントも含めた実装レシピはClaude Code Hooks実例カタログで扱っています。

デスクトップ通知だけで足りている人にもNotification hookは意味があります。通知センターを普段チェックしない運用や、社給端末で通知許可を管理者が絞っている環境では、hookでSlackやチャットツールに直接投げてしまう方が見逃しにくくなります。音とチャット通知を両方登録して、どちらか一方が届けば気づける状態にしておく使い方もできます。

スマホへのPush通知は別の仕組み

ここまでの設定はすべて、Claude Codeを動かしているマシンの画面やターミナルに向けた通知です。スマートフォンへのPush通知はagentPushNotifEnabledとinputNeededNotifEnabledという別の設定で、Remote Controlが接続されているときにClaude Codeのモバイルアプリへ送られます。仕組みが違うため、ターミナルベルとモバイルPush通知は両方同時に有効化できます。長時間タスクを外出先から確認したいならモバイルPush、手元で作業しながら気づきたいならターミナルベルやデスクトップ通知、という使い分けになります。

設定はモバイルアプリを入れてClaude Codeと同じアカウントでサインインし、OSの通知許可を承認したうえで、ターミナルから/configを実行してPush when Claude decides(タスク完了時などClaude側の判断で送る)とPush when actions required(権限確認や質問待ちのときに送る)のどちらか、または両方を有効にします。この2つに対応するagentPushNotifEnabledとinputNeededNotifEnabledはどちらも既定でfalseなので、/configから明示的に有効化しない限りモバイルへは何も届きません。

Push通知が来ない場合の切り分けは3つあります。/configに「No mobile registered」と表示されているなら、スマホ側でClaude Codeアプリを開いてプッシュトークンを更新すれば次回接続時に解消します。iOSでは集中モードや通知の要約機能がPush通知を遅らせたり抑えたりするので、設定 → 通知 → Claudeを確認します。Androidではバッテリー最適化が届くタイミングを遅らせることがあるため、Claudeアプリをバッテリー最適化の対象外にします。なお、接続元のターミナルを操作中や表示中はモバイルPush通知自体がスキップされる仕様なので、手元で作業しているのにPushが来ないのは想定どおりの挙動です。

通知チャンネルの使い分け

iterm2はiTerm2でのデスクトップ通知だけを明示的に有効にする値で、autoとほぼ同じ挙動になりますが、他の2つのターミナルを使う予定がないことをはっきりさせたいときに使えます。iterm2_with_bellはそこにベル通知も重ねる値で、画面を見ていなくても音で気づきたい場合に足します。運用としては、対応ターミナルを常用しているならautoのままで足り、非対応ターミナルや遠隔操作が多い環境ではterminal_bellを基本にしつつ、見逃せない合図だけNotification hookで別経路にも流す組み合わせが現実的です。

よくある質問

iTerm2で手順通りに設定してもまだ通知が来ないときは?

iTerm2側の「Notification Center Alerts」と「Send escape sequence-generated alerts」が両方有効になっているか、そしてmacOSの通知設定でiTerm2に通知許可が出ているかを確認してください。iTerm2側だけ設定してOS側の許可が無いと、通知は生成されても表示されません。

WarpやVS Code統合ターミナルではデスクトップ通知はどうなる?

これらはデスクトップ通知を受け取らないターミナルとして案内されています。preferredNotifChannelをterminal_bellにするか、Notification hookでコマンドを実行する方法に切り替えてください。

preferredNotifChannelをnotifications_disabledにするとNotification hookも止まる?

止まりません。Notification hookは組み込みの通知の代わりではなく並行して動く独立した仕組みなので、notifications_disabledにしてもhookの設定はそのまま実行されます。

スマホへのPush通知とターミナル側の通知は同時に使える?

使えます。モバイルPush通知はRemote Control経由の別機能で、ターミナルベルやデスクトップ通知とは独立した設定です。両方を有効にしておけば、手元にいるときはターミナル側、離れているときはスマホ側で気づけます。

スクリーンリーダーモードでも同じ設定で通知される?

スクリーンリーダーモードでは既定でターミナルベルが鳴るようになっており、preferredNotifChannelを明示的にterminal_bellにする必要はありません。読み上げ関連の詳細はClaude Codeスクリーンリーダー対応ガイドで扱っています。

モバイルPush通知はタスク完了だけに絞れる?

細かい絞り込みはできません。Push when Claude decidesとPush when actions requiredの2つのオン・オフ以外に、イベント単位の設定項目は用意されていません。タスク完了だけ受け取りたい場合は前者だけをオンにし、権限確認や質問待ちも知りたければ両方オンにする、という粒度になります。

まとめ

通知が届かない原因は、ほぼpreferredNotifChannelの既定値がターミナルを限定していることに集約されます。対応外のターミナルならterminal_bellへ切り替え、それでも足りなければNotification hookでコマンドを追加します。tmuxを使っている場合はパススルー設定が前提になる点だけ忘れないようにしてください。デスクトップとモバイルは別経路なので、両方設定しても構いません。