Zenn
🔔

Claude Code Hooksでterminal-notifierを使った完了通知を設定する方法

に公開
AI
macOS
terminal
automation
Claude
tech

Claude Code Hooksで開発効率を劇的に改善できます

Claude Code Hooksは、AI開発ツール「Claude Code」の強力な機能です。コードの生成や実行の各段階でカスタムアクションを自動実行でき、開発ワークフローを大幅に改善できます。

特に、macOSユーザーにおすすめなのが、terminal-notifierと組み合わせた完了通知システムです。この設定により、長時間の処理が完了した瞬間に通知を受け取れるようになります。

Claude Code Hooksとは？基本概念を理解しましょう

Hooksが解決する問題

Claude Code Hooksは、開発中のこんな悩みを解決します：

  • 長時間の処理が終わったことに気づかない
  • コードフォーマットを毎回手動で実行している
  • 危険なコマンドを実行前にチェックしたい
  • チーム全体で統一されたワークフローを維持したい

Hooksの仕組み

Claude Code Hooksは、Claude Codeの動作ライフサイクルの特定のポイントで実行されるシェルコマンドです。LLMの判断に依存せず、確実に実行されるのが最大の特徴です。

4つのHook Eventsを使い分けましょう

Claude Code Hooksには、用途に応じて使い分ける4つのイベントタイプがあります。

1. PreToolUse - 実行前の処理

実行タイミング: Claudeがツールパラメータ作成後、ツール実行前

主な用途:

  • 危険なコマンドのブロック
  • 事前バリデーション
  • 権限チェック

2. PostToolUse - 実行後の処理

実行タイミング: ツール実行成功直後

主な用途:

  • 自動コードフォーマット
  • ログ記録
  • 結果検証

3. Notification - 通知時の処理

実行タイミング: Claude Codeが通知を送信時

主な用途:

  • カスタム通知システム
  • 外部ツールとの連携

4. Stop - 処理完了時の処理

実行タイミング: Claude Codeが応答終了時

主な用途:

  • 完了通知（最もおすすめ）
  • クリーンアップ処理
  • 継続処理の判定

terminal-notifierでmacOSに美しい通知を送信しましょう

terminal-notifierとは

terminal-notifierは、macOSのコマンドライン用通知ツールです。シェルから直接macOSのNotification Centerに通知を送信できるため、Claude Code Hooksとの相性が抜群です。

インストール方法

terminal-notifierのインストールは非常に簡単です：

# Homebrewでインストール（推奨）
brew install terminal-notifier

# RubyGemsでインストール
gem install terminal-notifier

基本的な使用方法

まずは、terminal-notifierの基本的な使い方を覚えましょう：

# シンプルな通知
terminal-notifier -message "タスクが完了しました"

# タイトル付き通知
terminal-notifier -title "Claude Code" -message "処理が完了しました"

# サウンド付き通知
terminal-notifier -title "作業完了" -message "すべての処理が終了しました" -sound default

Claude Code Hooksの設定方法を覚えましょう

設定ファイルの場所

Hooksの設定は、以下のJSONファイルで管理します：

# ユーザー設定（全プロジェクト共通）
~/.claude/settings.json

# プロジェクト設定
.claude/settings.json

# ローカル設定（Git管理外）
.claude/settings.local.json

基本的な設定構造

Claude Code Hooksの設定は、以下の構造で記述します：

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

おすすめ設定：Stop Hookで完了通知を実装しましょう

基本的な完了通知設定

最もシンプルで効果的な設定から始めましょう。Claude Codeの処理完了時に通知を出す設定です：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "terminal-notifier -title 'Claude Code' -subtitle '処理完了' -message 'すべてのタスクが終了しました' -sound default"
          }
        ]
      }
    ]
  }
}

この設定により、Claude Codeが作業を完了するたびに、音付きの通知が届きます。

より高度な通知設定

セッション情報を活用した詳細な通知システムを構築できます：

#!/bin/bash
# ~/scripts/claude-completion-notify.sh

# 入力データから情報を取得
SESSION_ID=$(jq -r '.session_id')
STOP_HOOK_ACTIVE=$(jq -r '.stop_hook_active')

# 無限ループを防ぐ
if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
    exit 0
fi

# プロジェクト名を取得
PROJECT_NAME=$(basename "$PWD")

# 詳細な通知を送信
terminal-notifier \
    -title "Claude Code 🤖" \
    -subtitle "プロジェクト: $PROJECT_NAME" \
    -message "処理が完了しました (Session: ${SESSION_ID:0:8})" \
    -sound "Blow" \
    -group "claude-code-completion"

対応する設定ファイル：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/scripts/claude-completion-notify.sh"
          }
        ]
      }
    ]
  }
}

実践的な追加設定例を紹介します

危険なコマンドの事前チェック

PreToolUseで危険なコマンドを検出し、警告通知を出す設定です：

#!/bin/bash
# ~/scripts/claude-safety-check.sh

COMMAND=$(jq -r '.tool_input.command // ""')

if echo "$COMMAND" | grep -E "(rm -rf|sudo|passwd)" > /dev/null; then
    terminal-notifier \
        -title "⚠️ Claude Code 警告" \
        -message "危険なコマンドが実行されようとしています: $COMMAND" \
        -sound "Sosumi"
    
    echo "危険なコマンドが検出されました: $COMMAND" >&2
    exit 2  # コマンドをブロック
fi

自動コードフォーマット

ファイル編集後に自動でコードフォーマットを実行する設定です：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/prettier --write . 2>/dev/null || echo 'Prettierでフォーマットしました'"
          }
        ]
      }
    ]
  }
}

terminal-notifierの詳細オプションを活用しましょう

基本オプション

-title VALUE          # 通知のタイトル
-subtitle VALUE       # サブタイトル
-message VALUE        # メッセージ本文
-sound NAME           # サウンド名

高度なオプション

-group ID             # 通知グループ（重複防止）
-appIcon PATH         # カスタムアイコン
-contentImage PATH    # 添付画像
-open URL            # クリック時に開くURL
-execute COMMAND     # クリック時に実行するコマンド
-activate ID         # アクティブ化するアプリ

利用可能なサウンド

macOSで利用可能なサウンドは以下のディレクトリで確認できます：

ls /System/Library/Sounds/

よく使われるサウンド：

  • default - デフォルト音
  • Blow - ポップ音
  • Sosumi - アラート音
  • Glass - 軽快な音

セキュリティ対策を忘れずに実装しましょう

重要な注意事項

セキュリティベストプラクティス

安全なHookを作成するために、以下の点を必ず守ってください：

  1. 入力の検証: Hook内で外部入力を適切に検証する
  2. 変数のクォート: シェル変数は必ず "$VAR" でクォートする
  3. パストラバーサル対策: ファイルパスに .. が含まれていないかチェック
  4. 絶対パス使用: スクリプトには絶対パスを指定する
  5. 機密ファイル除外: .env, .git/, 秘密鍵などを避ける

安全なHookの例

#!/bin/bash
# セキュアなファイル処理の例

FILE_PATH=$(jq -r '.tool_input.file_path // ""')

# パストラバーサル攻撃の防止
if echo "$FILE_PATH" | grep -E "\.\." > /dev/null; then
    echo "不正なファイルパスが検出されました" >&2
    exit 2
fi

# 機密ファイルの保護
if echo "$FILE_PATH" | grep -E "(\.env|\.git/|id_rsa)" > /dev/null; then
    echo "機密ファイルへのアクセスは禁止されています" >&2
    exit 2
fi

echo "ファイル処理: $FILE_PATH"

トラブルシューティングガイド

よくある問題と解決方法

Hookが実行されない場合：

  • /hooks メニューで設定を確認してください
  • JSONファイルの構文をチェックしてください
  • ファイル権限を確認してください

コマンドが失敗する場合：

  • 手動でのコマンド実行をテストしてください
  • 絶対パスを使用してください
  • 環境変数を確認してください

無限ループが発生する場合：

  • Stop Hookで stop_hook_active をチェックしてください
  • 適切な終了条件を設定してください

デバッグ方法

# トランスクリプトモードで進行状況を確認
# Ctrl-R で表示

# Hook実行ログの確認
tail -f ~/.claude/projects/PROJECT_NAME/logs/

まとめ：Claude Code Hooksで開発効率を向上させましょう

Claude Code Hooksとterminal-notifierを組み合わせることで、開発ワークフローが劇的に改善されます。

得られる主なメリット

  • 即座の完了通知: 長時間処理の完了を見逃しません
  • 自動化の実現: 手動作業が大幅に削減されます
  • 一貫性の確保: チーム全体で統一されたワークフローを維持できます
  • セキュリティ向上: 危険なコマンドを事前にブロックできます

今すぐ始められる3ステップ

  1. terminal-notifierをインストール：brew install terminal-notifier
  2. 基本的なStop hookを設定：処理完了通知から始めましょう
  3. 段階的に機能を拡張：プロジェクトのニーズに応じてカスタマイズしましょう

Claude Code Hooksを活用することで、より効率的で快適な開発環境を構築できます。ぜひ、あなたのプロジェクトでも今日から試してみてください。

Discussion