cc-notifier-voice

cc-notifier-voice は、Claude Code の状態変化をデスクトップ通知、音声読み上げ、イベント別の通知音で知らせるプラグインです。macOS、Windows 11、WSL2 に対応し、必要な場合だけ Slack や汎用 HTTPS Webhook へ通知を転送できます。

AI に長い処理を任せている間、ターミナルを監視し続ける必要はありません。確認が必要になった瞬間、ツールが失敗した瞬間、作業が完了した瞬間を、別の作業をしている人へ確実に返すための小さなシグナル層です。

解決すること

Claude Code を使った開発では「AI が処理する時間」と「人が判断する時間」が交互に発生します。処理中ずっと画面を見ると集中が分断され、別作業へ移ると許可待ちや失敗を見落とします。

このプラグインは Claude Code Hooks を受け取り、イベントを次の通知経路へ振り分けます。

• OS のデスクトップ通知
• macOS / Windows のネイティブ TTS
• イベント種別ごとの通知音
• 任意で有効化する Slack Incoming Webhook
• 許可ホストを限定できる汎用 HTTPS Webhook

視覚、音声、外部通知はそれぞれ独立して有効・無効を設定できます。通知を増やすことではなく、今の作業環境で必要なシグナルだけを残すことが目的です。

対応イベント

SubAgent が動作している間は、親側の Stop を最終完了として通知しないよう抑制します。マルチエージェント作業で途中経過を完了通知と誤認しにくくするための制御です。

動作環境

セットアップ

ページ上部の2コマンドを Claude Code 内で実行し、インストール後に Claude Code を再起動します。初回通知時は OS の通知権限を許可してください。

設定ファイルは ~/.config/cc-notifier-voice/config に置きます。

mkdir -p ~/.config/cc-notifier-voice
cat > ~/.config/cc-notifier-voice/config << 'EOF'
CC_NOTIFIER_LANG=ja
CC_NOTIFIER_SPEED=250
CC_NOTIFIER_TTS_ENABLED=true
CC_NOTIFIER_VISUAL_ENABLED=true
CC_NOTIFIER_OUTBOUND_MESSAGE_MODE=summary_only
EOF

設定値は 設定ファイル > 環境変数 > デフォルト の順で解決されます。Hook は非インタラクティブなサブプロセスで動くため、.zshrc などのシェル初期化ファイルではなく専用設定ファイルを使います。

通知を作業環境に合わせる

チャンネルをイベントごとに絞る

CC_NOTIFIER_TTS_EVENTS と CC_NOTIFIER_VISUAL_EVENTS には all、または notification,permission,stop,tool-failure,completion のようなカンマ区切りのイベントを指定できます。

CC_NOTIFIER_TTS_EVENTS=permission,tool-failure,completion
CC_NOTIFIER_VISUAL_EVENTS=all
CC_NOTIFIER_COOLDOWN=5

音声は判断が必要なイベントだけ、視覚通知はすべて、といった役割分担が可能です。同一イベントの連続通知を抑える cooldown も秒単位で設定できます。

おやすみ時間を設定する

CC_NOTIFIER_QUIET_START=23:00
CC_NOTIFIER_QUIET_END=07:00

quiet hours の間は TTS と通知音を抑制します。深夜の自動処理や長時間セッションでも、視覚通知だけを残した運用に調整できます。

外部通知とセキュリティ

Slack と汎用 Webhook はデフォルトで無効です。ローカルのデスクトップ通知と TTS だけで使う場合、通知本文を外部へ送信しません。

CC_NOTIFIER_SLACK_ENABLED=false
CC_NOTIFIER_WEBHOOK_ENABLED=false
CC_NOTIFIER_REDACT_SENSITIVE=true
CC_NOTIFIER_OUTBOUND_MESSAGE_MODE=summary_only

macOS 用の CCNotifier.app は現在 Developer ID 署名なしで配布されています。起動前に同梱バイナリが事前登録済み SHA256 フィンガープリントと一致するか検証し、改ざんリスクを抑えています。Gatekeeper や組織のセキュリティポリシーに署名済みアプリが必須の場合は、この制約を確認してから導入してください。

向いているケース

• Claude Code に数分以上の処理を任せ、その間にレビューや文書作成を進める人
• 許可待ちやツール失敗へすぐ戻りたい開発者
• 複数ターミナル、複数ペイン、SubAgent を並行して使う作業環境
• ローカル通知を基本にしつつ、必要なイベントだけチームの Slack へ届けたい運用

ジョブスケジューラや監視基盤を置き換えるものではありません。Claude Code の対話的な作業リズムを、OS の通知機能につなぐ軽量なプラグインです。

公開情報

ソースコード、変更履歴、セキュリティポリシー、英語・日本語の設定ガイドは GitHub リポジトリ で公開しています。現在の公開版は v0.2.1、ライセンスは MIT License です。設定項目とプラットフォーム固有の注意点は 日本語設定ガイド を確認してください。