【Claude Code】Hooks機能でデスクトップ通知を設定してみた

はじめに

※今回はMacOS環境での例を紹介します。
Claude Codeを使用していると、以下のようなケースで気づいたら処理が止まっているといったことがあると思います。
・（ファイルの操作権限が必要であれば）ファイル操作のために必要な権限付与の許可待ち
・（質問であれば）質問の回答待ちもしくは深堀りのための逆質問
・（タスクを依頼していたら）タスク完了時
こまめに処理が止まっていないかを確認するのも大変です。
そこで、今回はClaude CodeのHooks機能を使用して、上記のようなケースにデスクトップ通知させる設定方法を紹介します。

Hooksとは

簡潔にまとめると、「Claude Codeセッション中の特定のポイントに、カスタム処理を差し込める仕組み」です。
まずは、これらの公式ドキュメントを読むことをおすすめします。

たくさんの '特定のポイント' （＝イベントタイプ）がありますが、例として以下のような利用方法があります。

PreToolUse(ツールが実行された直後に発火するフック)
・危険コマンドのブロック（rm -rfなど）
・機密ファイル保護（.envへのアクセスを拒否など）

PostToolUse(ツールが実行される直前に発火するフック)
・コード整形（Prettierなど）
・ログの記録

Notification(特定のイベント発生時に通知処理を実行するためのフック)
・通知（入力待ち、タスク完了）

だいたいのことは実現できそうなので、いろいろ試してみるのも面白いと思います。

・Hooksは並列処理のため、同じタイミングで発火する複数処理の順序は保証されません
・エラー時はタイムアウト60秒で処理が停止します

・Hooksコマンドは権限付与の許可を待たずにユーザーのフルアクセス権限で実行されるため、注意が必要です

デスクトップ通知の設定

（私はすべての環境に適用させたいのでホームディレクトリの）.claude/settings.jsonに以下のような記述を追加します。
※必要に応じてプロジェクト直下の設定ファイルを使用するなどしてください。
設定はこれだけです。
設定が完了すると、スクリプトエディタアプリから通知が届くようになります。（Macのデフォルトの仕様）

~/.claude/settings.json

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude finished responding\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Notification

条件フィルタ（matcher）を"matcher": ""とすることで、「Claudeが通知を出すすべてのタイミング」で発火するようにしています。
osascriptはmacOSのAppleScriptをCLIから実行する仕組みで、display notificationでネイティブ通知（Notification Center）を表示させます。

(ファイル操作の権限付与の許可待ち時)

Stop

Claude Codeが処理を終了したタイミングで発火させたい場合はNotificationではなく、Stopを使用します。

（回答終了時）

通知が飛ばない場合

・claudeを再起動しないと設定が適用されない場合があります。
・MacBookで「おやすみモード」などが有効になっていると通知が飛ばない場合があります。
・Macのシステム設定 >> 通知 >> スクリプトエディタの通知が許可されていることを確認してください

おまけ

スクリプトエディタアプリから通知が届くようになったのはいいものの、通知バナーをクリックすると毎回以下のようなウィンドウが開いてしまいます。

そこで、現在使用しているターミナルから通知が来るようにする方法を紹介します。
※一部対応できないターミナルがあるようです。
※今回ターミナルはGhosttyを使用しています。

Ghosttyに関するこちらの記事もおすすめです。

Macのシステム設定 >> 通知 >> Ghosttyの通知が許可されていることを確認し、
設定ファイルを以下のように修正します。

~/.claude/settings.json

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "printf '\\x1b]9;Claude finished responding\\x07' > /dev/tty"
          }
        ]
      }
    ]
  }
}

Notification

権限確認のような、「絶対に見逃してはいけないイベント」は、Claudeによってhooksとは別系統で強制通知されるそうです。
Ghosttyの通知を許可するだけで勝手に通知されるため、今回はあえてNotificationを設定していません。

Stop

これはClaudeの処理終了時（Stopイベント）にターミナルへ制御シーケンスを送っています。
printf '\x1b]9;{メッセージ}\x07'
これはOSC 9 (Operating System Command)というターミナル仕様です。
・\x1b] → OSC開始
・9; → 「通知を出せ」という命令
・\x07 → 終了
GhosttyはこのOSC 9を受け取るとmacOSのネイティブ通知を出します。
Claude → printf → OSC 9 → Ghostty → macOS通知

設定が適用されていれば、以下のようにGhosttyから通知がとどきます。
また、このバナーをクリックするとちゃんとClaude Codeの対象セッション画面が開きます。
（真ん中のタイトル行にはセッションタイトルが自動的に反映されるようです）

さいごに

terminal-notifierを使用したパターンもあるそうなので、気になった方はぜひ調べてみてください。