Claude Code の hooks でできること｜通知・自動整形・ファイル保護を公式ガイドで整理

Claude Code の hooks は、決まったタイミングでシェルコマンドを実行する仕組みです。公式ガイド「Automate actions with hooks」をもとに、自動化できる内容と設定時の注意点を整理します。

hooks とは何か

hooks は、ユーザーが定義するシェルコマンドです。Claude Code が、ライフサイクル上の特定の時点で実行します。

公式はこれを「決定的な制御」と説明しています。特定の動作が必ず起きる、という意味です。LLM が実行するかどうかを選ぶ方式とは異なります。

公式が挙げる用途は次の 3 つです。

  • プロジェクトのルールを強制する
  • 繰り返し作業を自動化する
  • Claude Code を既存のツールと連携させる

判断が必要な場面

ルールでは決められない判断には、prompt-based hooks と agent-based hooks があります。Claude モデルが条件を評価する方式です。

関連する拡張機能

公式は、ほかの拡張手段も紹介しています。

  • skills：Claude に追加の指示と実行可能なコマンドを与える
  • subagents：分離されたコンテキストでタスクを実行する
  • plugins：拡張機能をパッケージ化し、複数のプロジェクトで共有する

イベントのスキーマや JSON の入出力形式、async hooks、MCP ツール hooks は、別ページの Hooks reference にあります。このガイドは、よくある使い方と始め方の入門です。

最初の hook を設定する流れ

hook は、設定ファイルに hooks ブロックを追加して作ります。公式の手順は、Claude が入力待ちになったときにデスクトップ通知を出す例です。

1. 設定ファイルに追加する

~/.claude/settings.json を開き、Notification の hook を追加します。ファイルが無ければ作成します。macOS では osascript を使います。

すでに hooks キーがある場合は、全体を置き換えません。既存のイベントキーと並べて Notification を追加します。イベント名は、1 つの hooks オブジェクトの中のキーです。

作りたい内容を CLI で伝え、Claude に hook を書いてもらう方法もあります。

2. 設定を確認する

プロンプトで /hooks と入力すると、hooks ブラウザが開きます。追加した hook が Notification の下に出れば、登録されています。

3. 動作をテストする

Esc で CLI に戻ります。ステータスバーに ⏸ manual mode on と出るまで Shift+Tab を押します。許可が必要な作業を Claude に頼み、ターミナルから別の画面へ切り替えます。デスクトップ通知が届けば成功です。

hooks で自動化できること

公式の例として挙がっているのは、次のような用途です。

  • 編集後にファイルを整形する
  • 実行前にコマンドをブロックする
  • Claude が入力を待つときに通知する
  • セッション開始時にコンテキストを注入する

各例には、設定ファイルへそのまま追加できる設定ブロックが付いています。

入力待ちをデスクトップ通知で知らせる

Notification イベントを使います。Claude が入力や許可を待っているときに発火します。ターミナルを見続けなくても、別の作業ができます。

コマンドは環境ごとに違います。

  • macOS：osascript
  • Linux：notify-send
  • Windows：PowerShell のメッセージボックス

通知が出ないときの注意も、環境ごとに書かれています。

  • macOS：通知は Script Editor アプリ経由です。通知権限が無いと、コマンドは黙って失敗します。システム設定の通知で、Script Editor を許可します。
  • Linux：notify-send にはデスクトップ通知デーモンが必要です。ヘッドレスサーバー、SSH セッション、多くのコンテナには無い環境です。
  • Windows：画面隅の通知ではなくダイアログが開きます。ターミナルの後ろに隠れることがあります。WSL では、powershell.exe が PATH 上で使える必要があります。

matcher で通知の種類を絞る

matcher が空なら、すべての通知タイプで発火します。絞りたい場合は、値を指定します。主な値は次のとおりです。

matcher発火するタイミング
permission_prompt承認が必要で、プロンプトが約 6 秒待たれたとき
idle_prompt応答完了から約 60 秒たち、入力がないとき
auth_success認証が完了したとき
agent_completedバックグラウンドセッションが完了または失敗したとき

agent_completed は、agent view を開いている間だけ発火します。このほかに、MCP の elicitation 系、使用量上限後の自動再開系、plugin_notification があります。

編集のたびにコードを自動整形する

PostToolUse イベントと、Edit|Write の matcher を組み合わせます。ファイル編集ツールの後だけ実行されます。

コマンドは、jq で編集されたファイルのパスを取り出し、Prettier に渡します。設定先は、プロジェクトルートの .claude/settings.json です。

成功しても、会話には何も表示されません。動いたかどうかは、ファイルが整形されたかで確認します。

Bash コマンドによる書き換えも含めて整形したいときは、FileChanged hook を使うよう案内されています。

保護したいファイルへの編集をブロックする

.env、package-lock.json、.git/ 配下などを守る例です。ブロックされると、Claude は理由のフィードバックを受け取ります。そのため、別のやり方に切り替えられます。

手順は次の 4 段階です。

  1. .claude/hooks/protect-files.sh にスクリプトを作り、保護パターンと一致したら終了コード 2 で終了する
  2. macOS と Linux では chmod +x で実行可能にする
  3. PreToolUse hook として、Edit|Write の前に実行するよう登録する
  4. .env へのコメント追加を Claude に頼み、ブロックを確認する

終了コード 2 が、ブロックの合図です。標準エラーに出した Blocked: のメッセージが、Claude に渡ります。

コンパクション後にコンテキストを再注入する

コンテキストウィンドウが満杯になると、コンパクションで会話が要約されます。このとき、細部が失われることがあります。

SessionStart hook に compact の matcher を付けると、コンパクションのたびに情報を入れ直せます。コマンドが標準出力に書いたテキストは、Claude のコンテキストに追加されます。

公式の例は、echo でプロジェクトの規約を伝える内容です。git log --oneline -5 のような動的な出力も使えます。毎回のセッション開始時に渡すだけなら、CLAUDE.md を検討するよう書かれています。

設定ファイルの変更を監査する

ConfigChange イベントは、外部のプロセスやエディタが設定ファイルを変更したときに発火します。記録することも、ブロックすることもできます。

公式の例は、変更ごとに ~/claude-config-audit.log へ JSON を 1 行追記するものです。内容は、タイムスタンプ、変更元、ファイルパスです。

matcher で絞れる種類は、user_settings、project_settings、local_settings、policy_settings、skills です。変更を止めるには、終了コード 2 で終了するか、{"decision": "block"} を返します。

ディレクトリ変更時の環境読み込み

Claude の Bash ツールは、direnv のような環境変数の切り替えを自動では拾いません。ガイドは、SessionStart hook と CwdChanged hook の組み合わせを案内しています。詳しい手順は、公式ガイドの該当の節で確認できます。

つまずきやすい点と要件

  • 既存の hooks キーは置き換えず、イベントキーを並べて追加する
  • 登録の確認は、/hooks の一覧で行う
  • 成功した hook は会話に何も出さないため、結果は成果物やログで見る
  • スクリプトを呼ぶ hook には、実行権限が必要
  • 通知の前提は OS ごとに違う

バージョン要件もあります。

  • quota_auto_resume_fired、quota_auto_resume_stale、quota_auto_resume_disabled：v2.1.234 以降
  • サンドボックス化されたコマンドのネットワーク要求に対する permission_prompt：v2.1.246 以降
  • チームメイトの端末セットアップの質問に対する agent_needs_input：v2.1.248 以降

permission_prompt のタイミングは、ターミナルと、Claude Desktop や VS Code 拡張などで異なります。

よくある疑問

hooks と CLAUDE.md は何が違いますか

hooks は、決まったタイミングで必ず実行されるコマンドです。セッション開始時に毎回同じ情報を渡すだけなら、CLAUDE.md が向くと公式は述べています。

さらに詳しく知るには

全イベントの一覧、スキーマ、JSON の入出力形式は、公式の Hooks reference にあります。

出典

内容は確認日時点のものです。最新の情報は、出典の公式ページで確認してください。

本記事は、公式情報（公式ページ code.claude.com）の内容を整理したものです。私が実際に使った感想ではありません。アフィリエイトリンクは含みません。 確認日: 2026-10-28 / 出典: https://code.claude.com/docs/en/hooks-guide