Claude Code Hooksとは？設定方法と使い方・通知の実例を解説

最終更新日:2026/08/20

Claude Codeには、ファイル編集後の自動フォーマットや危険なコマンドの実行前ブロックなど、指定したタイミングで処理を確実に実行できるHooksという機能があります。本記事では、Hooksの仕組みから設定方法、代表的なイベント、通知設定、活用例、動作しない場合の対処法まで解説します。この記事を読めば、自分の開発フローに合わせたHooksを設定し、フォーマットや通知、安全ガードといった定型処理を自動化できるようになります。

Claude Code Hooksとは？仕組みと役割

Hooksとは、Claude Codeのライフサイクルにおける特定のタイミングで、指定した処理を自動実行する機能です。

command型のHooksは、条件に合致するたびに毎回自動実行されます。フォーマットやコマンド検証といった処理を、Claudeモデルの判断に頼らず確実に行える点が特徴です。

一方でprompt型やagent型のHooksは、Claudeモデルによる単発の判定処理を組み込む仕組みのため、Hooks全体が常に決定論的というわけではありません。

用途に応じてtypeを使い分ける点が、Hooksを設計するうえでの前提になります。

関連記事：Claude Code入門ガイド｜インストールから基本操作・活用方法まで解説

参考：Claude Code Docs｜Hooks reference

Hooksで自動化できること

Hooksを使うと、ファイル編集後の自動フォーマット、危険なコマンドの実行前ブロック、応答完了時の通知、セッション開始時のコンテキスト注入、監査ログの記録といった処理を自動化できます。

公式ガイドは、代表的な用途として、入力待ちや承認待ちの通知、編集ファイルへの自動フォーマット、保護ファイルへの編集ブロック、コンテキスト圧縮後の情報再注入、設定変更の監査ログ記録、作業ディレクトリやファイル変更時の環境変数の再読み込み、特定の許可プロンプトの自動承認という7つのユースケースを挙げています。

いずれも、Claude Codeを日常的に使うなかで繰り返し発生する手作業を、スクリプトに置き換える具体例として参考になります。手元の開発フローに近いパターンから設定を始めると、Hooks導入の効果を実感しやすくなります。

Hooksで利用できる5つの実行タイプ

Hooksのハンドラーには5種類のtypeが用意されており、呼び出す対象と用途がそれぞれ異なります。

agent型はReadやGrep、Globなどのツールを使えるサブエージェントに検証を委ねる機能で、公式ドキュメントでは実験的な機能として位置づけられており、今後仕様が変更される可能性があります。

Hooksとスキル・サブエージェントの違い

Claude Codeの拡張手段には、Hooks・Skills・Subagentsという3種類があり、それぞれ実行の性質と用途が異なります。

Hooksは条件に合致するたびに毎回自動実行される決定論的な仕組みで、フォーマットやブロック、通知、監査ログといった処理に向いています。

Skillsは必要なときに読み込む手順書であり、定型作業を再利用する場面で役立ちます。Subagentsは独立したコンテキストでタスクを委譲する仕組みで、大規模な調査や検証に適しています。

参考：Claude Code Docs｜Hooks reference

絶対に守らせたいルールはHooks、再利用したい作業手順はSkills、重い調査や検証はSubagentsという判断基準で考えると、拡張手段を選びやすくなります。

Claude Code Hooksの設定方法

Hooksは設定ファイルのJSONで定義され、構造は「イベント名 → matcher（マッチャーグループ）→ hooks（ハンドラー配列）」という3階層のネストになっています。

イベント名でHooksが発火するタイミングを選び、matcherで発火条件を絞り込み、hooks配列で実行するコマンドやURLを指定する流れです。

matcher階層や配列の入れ子を誤ると、エラーが表示されないまま設定全体が無視されることがあります。記述後は必ず動作確認をしましょう。

最小構成のHooksを設定する手順

最初の一歩として、通知1件だけのHooksから設定を始めると、仕組みを理解しやすくなります。

まず~/.claude/settings.jsonを開き、Notificationイベント用の最小構成のJSONを貼り付けて保存します。

次に、Claude Codeで/hooksコマンドを実行し、貼り付けた設定が一覧に登録されているかを確認します。

続いて、実際に許可が必要な操作をClaudeに依頼してターミナルから離れるなど、通知が届く場面を意図的に作り、動作を試します。

最小構成で成功体験を得たあとに、3階層構造やmatcher、ifといった発展的な設定を学ぶと、仕組みをより深く理解できます。

settings.jsonの配置場所と適用範囲

Hooksの設定ファイルは複数の場所に配置でき、置き場所によって適用範囲と共有可否が変わります。

参考：Claude Code Docs｜Hooks reference

チーム共通のルールはコミットするプロジェクト設定へ、個人設定はGit管理外のローカル設定へ分ける運用が有効です。

matcherとifによる発火条件の絞り込み

matcherは、どのツールや種別でHooksを発火させるかを絞り込む項目です。

空文字や*を指定すると全件が対象になり、Edit|Writeのようにパイプで区切ると複数ツールを同時に指定でき、正規表現による記述も可能です。

ifフィールドは、PreToolUse・PostToolUse・PostToolUseFailure・PermissionRequest・PermissionDeniedという5つのツール系イベントでのみ評価され、それ以外のイベントに設定してもHook自体が実行されません。

ツール名だけでなく、Bash(git *)やEdit(*.ts)のように引数を含めた条件で発火範囲を絞り込むことも可能です。

特定のバージョン番号を本文に残す場合は、公式の変更履歴で初出バージョンを確認したうえで記載することをおすすめします。

参考：GitHub｜claude-code /CHANGELOG.md

/hooksコマンドで設定を確認する手順

Claude CodeのCLIで/hooksと入力すると、設定済みのHooksをイベント別に一覧表示する読み取り専用メニューが開きます。

メニューでは、command・prompt・agent・http・mcp_toolという5種類のtypeがラベル表示され、matcherや定義元の設定ファイル、コマンド内容やURLまで確認できます。

定義元は、ユーザー設定・プロジェクト設定・ローカル設定・プラグイン・セッション内登録・組み込みという区分で示され、どの設定ファイルに書いたHooksが実際に動いているかを把握するのに役立ちます。

ただしメニューは閲覧専用であり、追加や変更、削除については、settings.jsonを直接編集するか、Claude自身に依頼して修正する必要があります。

Claude Code Hooksの主なイベントと使い方

Hooksは、セッション単位で発火するSessionStartやSessionEnd、ターン単位で発火するUserPromptSubmitやStop、ツール呼び出しのたびに発火するPreToolUseやPostToolUseなど、異なる周期で動作します。

各ハンドラーはstdinでイベントのJSONを受け取り、終了コードとstdout・stderrで結果を返す仕組みです。

実務ではcommand型のHooksが大半を占めており、ほかのtypeは判断が必要な場面で補助的に組み合わせる形になります。

Claude Code Hooksのイベント一覧

Claude Codeの公式リファレンスには、現行バージョンで約30種類のイベントが掲載されています。

分類すると、SessionStartやSessionEndといったセッション単位のイベント、UserPromptSubmitやStopなどターン単位のイベント、PreToolUseやPostToolUseなどツール呼び出しごとのイベント、Notificationなど通知や入出力補助のイベントに整理できます。

ほかにも、ConfigChangeやFileChangedなど設定・環境変化に関するイベント、TaskCreatedやSubagentStartなどタスク・サブエージェントに関するイベント、PreCompactやPostCompactといったコンテキスト管理のイベントが存在します。

本記事では、利用頻度の高いSessionStart・UserPromptSubmit・PreToolUse・PostToolUse・Notification・Stopの6イベントに絞って詳しく解説します。

参考：Claude Code Docs｜Hooks reference

代表的なイベントと発火タイミング

実務でよく使われる代表イベントは、SessionStart・UserPromptSubmit・PreToolUse・PostToolUse・Notification・Stopの6つです。

参考：Claude Code Docs｜Hooks reference

PreToolUseはツール実行前に発火してブロックが可能で、危険コマンドのブロックや自動承認に使われます。

PostToolUseはツール実行の成功後に発火し、取り消しはできないため、自動フォーマットやlint、テストの実行に向いています。

Notificationは承認待ちや入力待ちの発生時、Stopは応答完了時に発火し、通知や検証ループの起点として利用されます。

終了コードとJSON出力による制御

Hooksの制御は、終了コードとJSON出力の組み合わせで決まります。終了コード0はHookの実行成功を意味し、stdoutにJSONが出力されていれば、その内容にもとづいた許可・拒否・追加コンテキストなど構造化された制御が行われます。

終了コード2はブロッキングエラーで、stderrの内容がClaudeへフィードバックされますが、実際に処理をブロックできるかどうかはイベントによって異なります。

例えばPreToolUseはツール呼び出し自体をブロックできる一方、PostToolUseはツールがすでに実行済みのため取り消せず、stderrがClaudeに提示されるだけです。

それ以外の終了コードは、原則として非ブロッキングエラーとして扱われます。

JSONによる構造化制御を使う場合は終了コード0で出力する必要があり、終了コード2の場合はstdoutのJSONが無視されてstderrが優先される点に注意が必要です。

通知を活用する（Mac・Windows・WSL・Linux）

Hooksを使うと、応答完了や承認待ちのタイミングでデスクトップ通知や通知音を鳴らせるため、PC画面から離れていても処理の完了に即座に気づけます。

通知には主に、承認待ちや入力待ちで発火するNotificationイベントと、応答完了で発火するStopイベントの2系統を使います。

Claude Code本体の処理をブロックしたくない場合は、async: trueを付けると非同期実行になります。

関連記事：【2026年最新】Claude Codeのコマンド一覧！見つからないときの解決策も　

参考：Claude Code Docs｜Hooks reference

macOSで通知・音を鳴らす設定

設定はsettings.jsonのhooks項目に、command型のハンドラーとしてosascriptやafplayのコマンドを記述する形になります。

注意点として、osascriptによる通知はスクリプトエディタへの通知許可が事前に与えられていない場合、エラーが表示されず失敗します。

対処法として、初回はターミナルで一度コマンドを実行したうえで、システム設定の通知欄からスクリプトエディタの通知を許可する操作が必要です。許可後に同じコマンドを再実行すると、通知が正常に表示されます。

Windows・WSLで通知を出す設定

Windowsでは、powershell.exeによるメッセージ表示や、BurntToastモジュールを使ったトースト通知によって、macOSと同等のデスクトップ通知を実現できます。

現行版のClaude CodeではWindows向けのcommand Hookにshell: “powershell”を指定でき、この場合Hooksが直接PowerShellを起動するため、CLAUDE_CODE_USE_POWERSHELL_TOOLの設定は不要です。

shellを省略した場合の既定は”bash”で、Git Bashが未インストールのWindows環境では”powershell”が使われます。

WSL環境やVS Code内蔵ターミナルからClaude Codeを使う場合は、通知そのものはLinux側ではなくWindows側の仕組みを呼び出す構成にする必要があります。

BurntToastモジュールは初回のみインストールが必要で、Import-Module BurntToastのあとにNew-BurntToastNotificationコマンドを実行する形で通知を表示します。

Linuxで通知を出す設定

ネイティブのLinux環境では、notify-sendコマンドを使ってデスクトップ通知を表示できます。

notify-sendはlibnotify-binなどのパッケージに含まれており、NotificationイベントやStopイベントのcommand型ハンドラーとして、通知タイトルと本文を引数に指定するだけで動作します。

notify-sendが未インストールの環境では、ディストリビューションのパッケージマネージャーを使って導入が必要です。

たとえばUbuntuやDebian系ではapt install libnotify-bin、Fedoraではdnf install libnotify、Arch Linuxではpacman -S libnotifyといったコマンドで導入できます。

導入後は、macOSやWindowsと同様に、Stopイベントと組み合わせて応答完了の通知を出す設定が可能になります。

実務で役立つClaude Code Hooksのおすすめ活用例

通知以外にも、編集後の自動フォーマット、危険コマンドの実行前ブロック、保護ファイルの編集防止、テストやlintの自動実行、監査ログの記録といった実務的な活用例があります。

導入順序としては、まずStopイベントの通知1行から始め、自動フォーマット、危険コマンドブロック、テスト自動実行という順に段階的に増やす進め方が無理のない方法です。

なお、Stop Hookは通知やログといった受動的処理だけでなく、完了条件の検証を目的とした継続・検証ループにも公式に利用できます。

検証ループとして使う場合は、条件が将来的に解消可能であることを確認したうえで、入力JSONのstop_hook_activeフィールドがtrueであれば終了コード0を返し、ループを止める実装が必須です。

参考：Claude Code Docs｜Hooks reference

編集後の自動フォーマットと品質チェック

PostToolUseにEdit|Writeのmatcherを設定すると、Claudeがファイルを編集または作成するたびにフォーマッターやlinterを自動実行できます。

設定例としては、jqコマンドで編集ファイルのパスをJSON入力から抽出し、そのパスをPrettierやgofmt、ruff、eslintといったツールに渡す構成が一般的です。

PostToolUseはツール実行後に発火するイベントのため、フォーマットやlintでエラーが検出された場合は、その結果がClaudeにフィードバックされます。

結果を受け取ったClaudeは、次のターンで自動的に修正を試みるため、「書く→確認する→直す」という一連のループを設定だけで組み立てられます。

手作業でのフォーマット指示を毎回出す必要がなくなり、コードの品質を安定させる効果が見込めます。

危険コマンドのブロックと安全ガード

PreToolUseにBashのmatcherを設定すると、rm -rfやDROP TABLEといった破壊的なコマンドを、実行前の段階で検出してブロックできます。

スクリプトはstdinから渡されるJSONを読み取り、コマンド文字列に危険なパターンが含まれる場合は終了コード2でブロックし、含まれない場合は終了コード0でそのまま通す構成が基本形です。

注目したい点として、permissionDecision: “deny”を返すHookは、bypassPermissionsモードや–dangerously-skip-permissionsオプションを使った場合でもブロックが有効に働きます。

ユーザー側の権限モード設定では回避できない安全ガードを組み込める点は、command型Hooksならではの強みといえるでしょう。

組織で共有する場合は、プロジェクト設定へコミットしておくと、チーム全体で同じガードを適用できます。

特定の許可プロンプトを自動承認する設定

ExitPlanModeなど、毎回同じ内容で承認しているツール呼び出しについては、PermissionRequestイベントを使って自動承認する設定が有効です。

matcherを対象ツールに絞り込んだうえで、{“hookSpecificOutput”: {“hookEventName”: “PermissionRequest”, “decision”: {“behavior”: “allow”}}}というJSONをstdoutに出力するcommand型のHookを登録すると、条件に合致する呼び出しについて確認ダイアログを省略できます。

注意点として、matcherを.*や空文字にすると、対象範囲を絞らずに全プロンプトを自動承認してしまい、危険な操作まで確認なしで通る恐れがあります。

承認対象は必要最小限のツールに絞り込む運用が望ましいでしょう。

また、非対話モード（-pオプション）では、Agent SDKのcanUseToolコールバックがプロンプトを供給する場合を除き、PermissionRequestイベントは発火しません。素の-p実行や–permission-prompt-toolを使う場合は、同様の制御にPreToolUseイベントを使う必要があります。

Claude Code Hooksが動かないときの対処法

Hooksが動作しない場合の原因は、大きく分けて4つに整理できます。

設定が反映されていない、matcherがツール名と一致していない、スクリプトに実行権限がない、JSONの記述が不正、という4パターンです。

設定ファイルの変更は、通常はファイル監視の仕組みによって自動的に読み込まれます。

数秒待っても/hooksメニューに変更が反映されない場合に限り、JSON構文の誤り（末尾カンマなど）や配置場所の誤りを確認したうえで、セッションを再起動する対処が有効です。

参考：Claude Code Docs｜Hooks reference

設定が反映されない・マッチャーが一致しない場合

/hooksメニューに設定したHooksが表示されない場合は、まずJSONの構文を確認します。

末尾に余分なカンマが残っていたり、JSON内にコメントを記述していたりすると、設定ファイル全体が読み込まれない原因になります。

あわせて、設定ファイルの配置場所が意図した範囲（ユーザー設定・プロジェクト設定・ローカル設定）と一致しているかも確認が必要です。

数秒待っても反映が確認できない場合は、セッションの再起動を試します。

matcherは大文字小文字を区別するため、BashやEdit、Writeといったツール名が正確な表記になっているか、PreToolUseとPostToolUseなどイベント種別が意図どおりに指定されているかも、あわせて見直す対象になります。

スクリプトエラー・JSON検証エラーが出る場合

「command not found」というエラーが出る場合は、スクリプトのパス指定を絶対パスや${CLAUDE_PROJECT_DIR}による参照へ変更し、chmod +xで実行権限を付与すると解決できます。

「jq: command not found」というエラーは、jqコマンド自体が未インストールであることが原因のため、パッケージマネージャーでの導入が対処法になります。

見落としやすい原因として、.bashrcなどシェルの起動プロファイルが無条件でechoコマンドの出力を行っていると、その文字列がHooksのJSON出力に混入し、検証エラーを引き起こすケースがあります。

対処法として、if [[ $- == *i* ]]という条件文を使い、対話シェルの場合のみechoを実行するよう起動プロファイルを修正する方法が公式に案内されています。

Stop Hookでループが止まらない場合

Stop Hookは、通知やログといった受動的処理に使う場合は安全に運用できますが、完了条件の検証を目的とした継続・検証ループとして使うことも、公式ドキュメントで正式にサポートされています。

検証ループとして設計する場合は、まず検証条件が将来的に解消可能な内容であることを確認します。

そのうえで、入力JSONに含まれるstop_hook_activeフィールドがtrueであれば、早期に終了コード0を返してループを止める実装が必須です。

Claude Codeには、ブロックが一定回数連続すると自動的にHookを上書きしてターンを終了させる保護機構が備わっており、正当な理由で多くの反復が必要な場合は、環境変数によってブロック上限を引き上げる対応が可能です。

Claude Code Hooksを使う際のセキュリティ上の注意点

Hooksはサンドボックスを介さず、ユーザー権限のまま実行される仕組みです。

そのため、設定ミスや悪意あるHookが原因で、ファイル削除や機密情報の漏えい、任意コードの実行といった事態が発生する可能性があり、公式ドキュメントでもこの点が明示的に警告されています。

対策としては、Hooksを本番用コードと同様に小さく明示的な内容に保つこと、機密情報を含む設定はローカル設定ファイルへ分離してGit管理から外すことが基本になります。

組織で運用する場合は、管理ポリシー設定とallowManagedHooksOnlyを組み合わせることで、承認済みのHooksのみに利用範囲を制限する運用も可能です。

参考：Claude Code Docs｜Hooks reference

まとめ

Claude Code Hooksは、フォーマットやコマンド検証、通知、監査ログといった処理を、Claudeモデルの判断に頼らず確実に実行できる仕組みです。

command・http・mcp_tool・prompt・agentという5種類のtypeを用途に応じて使い分け、settings.jsonの配置場所やmatcher、ifによる条件を適切に設定することで、開発フローに合わせた自動化を組み立てられます。

まずはStopイベントの通知1件から設定を始め、自動フォーマットや危険コマンドのブロックへと段階的に範囲を広げていくと、無理のない形でHooksを活用できます。

あわせて、サンドボックスなしで実行される仕組みである点を踏まえ、セキュリティ面の注意点を守りながら運用することが重要です。

アイスマイリーでは、生成AI のサービス比較と企業一覧を無料配布しています。課題や目的に応じたサービスを比較検討できますので、ぜひこの機会にお問い合わせください。

AIsmiley編集部

株式会社アイスマイリーが運営するAIポータルメディア「AIsmiley」は、AIの専門家によるコンテンツ配信とプロダクト紹介を行うWebメディアです。AI資格を保有した編集部がDX推進の事例や人工知能ソリューションの活用方法、ニュース、トレンド情報を発信しています。

・Facebookでも発信しています @AIsmiley.inc
・Xもフォローください @AIsmiley_inc
・Youtubeのチャンネル登録もお願いいたします@aismiley
メルマガに登録する