Claude Code Hooks とは?

要約
Claude Code Hooks は、Claude Code(CC)に任意のシェルコマンドを紐づけて実行できる仕組みです。特定のツールの使用前後、または通知・終了などのイベントタイミングで、自動的にコマンドを走らせることができます
意見はこのエリアに表示されます
アイキャッチ画像

Claude Code Hooks が便利なので、以下にまとめておきます。

Claude Code Hooks とは?

Claude Code Hooks は、Claude Code(CC)に任意のシェルコマンドを紐づけて実行できる仕組み

これは、特定のツールの使用前後、または通知・終了などのイベントタイミングで、自動的にコマンドを走らせることができる

CLAUDE.md に書いてた不安定な指示をやめて、フックというものを使って確実に実行させようやってことです

LLM に処理を任せるだけでなく、「ファイル編集後に音を鳴らす」「ログを残す」「外部ツールを実行する」など、人間の手動操作を減らす手段ってことですな

なぜ便利なのか?

Claude Code はコードの編集や実行、ターミナル操作などを対話的に行える強力なエージェントだが、「確実に実行してほしいこと」があるとき、プロンプトだけでは不安定なことがある

Hooks を使えば、以下のような「必ずやってほしいこと」を機械的に保証できる

  • 処理ログの記録
  • フォーマッターの自動実行
  • 編集完了後の通知音
  • セキュリティチェック(特定のディレクトリに触れさせない)
  • Slackやメールなどへの通知連携

フックイベント

Claude が外部ツールやファイル操作などの「ツール処理(Tool Call)」を行うときに、それに関連して動作する追加処理のこと。hooks.json に定義しておくことで、任意のシェルコマンドや通知、ログ記録などを自動で実行させることができる

イベント名発火タイミング主な用途の例
PreToolUseツール処理の直前(処理前)に呼び出される安全確認・入力バリデーション・キャンセルなど
PostToolUseツール処理の直後(処理後)に呼び出されるログ出力・通知音・コスト計測など
Notification処理とは関係なく、stderr の通知として実行される通知メッセージの表示など
StopClaude のツール使用を止めるときに呼び出される実行の強制停止・中断前フック

開発者視点で言えば、「ミドルウェア的な挿し込みポイント」ですね

マッチャー

「マッチャー(matcher)」とは、Claude Code Hooks において、どのツール操作に対してフックを実行するかを指定する条件のこと

フックイベント:PreToolUse

Claude がツールのパラメータを生成した後、実行前に呼び出されるフック

マッチャー説明
Taskエージェントのタスク実行
Bashシェルコマンドの実行
Globファイルパターンにマッチする操作
Grepコンテンツ検索
Readファイルの読み取り
Writeファイルの書き込み
Editファイルの編集
MultiEdit複数ファイルの同時編集
WebFetch外部リソースの取得(Web操作)
WebSearchWeb検索

特徴

  • | を使えば「OR条件」で複数指定できる
  • 正規表現ではないが、名前ベースでマッチングされる
  • 特定の操作だけをトリガーにしたいときに便利

Claude が Bash(シェル)や WebFetch(外部リソース取得)を実行しようとしたときにだけ、このフックが走る

基本の設定手順

  1. Claude Code のチャット欄で /hooks と入力し、Enter
  2. PostToolUse を選択(例:ツール使用後に発火)
  3. + Add new matcher...Write|Edit|MultiEdit と入力
  4. + Add new hook... → 任意のコマンドを入力
  5. 保存先を Local にして .claude/settings.local.json に保存

例1:処理完了時刻の記録

Claude がファイルを編集した直後、現在時刻をログとして表示する。これは ctrl + R の transcript モードでも確認できる

例2:音で知らせる

macOS 標準の通知音である Glass を再生する。ファイル編集後に "キンッ?" という音が鳴ることで、手を止めずに Claude の処理完了が分かる

例3:使用量の確認

Claude Code のセッションごとの使用コストやトークン消費を表示する CLI。いやー、スター伸びましたね!ワイは嬉しいね。これ、Hooks に組み込めば、自動的にコスト意識も高まる

例:ランダムなポエムを表示

これを紹介しておきたい

何か、CLI って気が滅入るときあるやん?そんなときは、これよ

画像の説明を入れてください
メッセージをつぶやくウシのアスキーアートw

brew install fortune cowsay をしておけば、処理完了のたびに名言やジョークを牛さんがつぶやくわけ。誰が考えたんやろな

ワイ、正直、Claude Code Hooks より、この牛が気になってしまった。いや、さっき知ったのよ

全部もってかれたね

想像してみ、今から30年後。あらゆるソフトウェアが停止した中、多分これは生き残ってる気がするのよ

荒廃した世界で、一人のレジスタンスが、地下でCLI 叩いたら、唯一これが出てくるの

これ考えた人、どんな気持ちで作ったのかな?

きっと、優しい人だよね

設定ファイルの全体例

実用的なコマンド例(作業ログ・通知)

コマンド説明
date '+%Y年%m月%d日(%a)%H:%M:%S'タイムスタンプを表示(処理完了ログ用)
echo '✅ Claudeがファイル編集しました' >> ~/claude-log.txtログファイルに記録
afplay /System/Library/Sounds/Glass.aiffMac の通知音(作業完了を耳で確認)
osascript -e 'display notification "Claudeが完了しました" with title "Claude Code"'macOS の通知を表示(視覚的フィードバック)
open .Finder を開く(作業ディレクトリをすぐ確認)
npx ccusage@latestClaude Code の使用ログを表示(cc ユーザー限定)

MCP

Claude Code Hooks における MCP との連携とは、「MCP を使って Claude がツールを呼び出したときに、自動で何か(シェルコマンドなど)を実行させる」という仕組み

Claude の /hooks において、tool_name にマッチする具体的な MCP のツール名(例: mcp_supabase_execute_sql)を指定すれば、そのツール実行にフックを発火できる

用途matcher 例実行内容例
GitHub検索ログ保存mcp__github__search_repositories検索キーワードをログに残す
ファイルアクセス監視mcp__filesystem__.*アクセス日時とパスを記録
Supabase系すべてに通知mcp__supabase__.*Slackに通知 or ローカル通知音再生
書き込み動作すべて検知mcp__.*__write.*バリデーションスクリプトを通す

トラブルシュート

  • コマンドが実行されない?

    • .claude/settings.local.json の構文エラーがないか確認
    • /hooks で GUI 上から設定確認・修正可能
  • afplayfortune が動かない?

    • brew install afplay fortune cowsay などで事前にインストールを
  • transcript に出力されない?

    • stderr ではなく stdout を使う(echo など)

応用アイデア

  • PreToolUse にセキュリティチェックを挟み、本番ファイルの書き換えをブロック
  • Notification フックに osascript で macOS 通知を表示
  • Stop フックで「続行条件が満たされない限り停止を防ぐ」
  • 編集対象のファイル名や内容をロギング
  • Git 操作との連携(auto-commit など)

Hooks をうまく活用すれば、Claude Code をセミ自動化IDEのように拡張できます。特に「Claude に何をさせているかを可視化したい人」「セキュアな運用をしたい人」には必須機能とも言える

今後も使える hook コマンドやベストプラクティスを見つけ次第、追記していくよ

Explore More
関連記事はありません。