Claude Code hooksの使い方｜設定手順と実践レシピ

「Claude Code hooksの使い方が知りたい！」
「Claude Code hooksって結局なにができるの？」

Claude Codeを毎日使っていると、気になることが出てきます。
編集のたびに自分でフォーマッターを実行する、長い作業の終わりに気づかない、危険なコマンドにヒヤッとする。

そこで使いたいのがClaude Code hooksです。ライフサイクルの特定タイミングで自動実行されるコマンドの仕組みで、設定ファイルに書くだけで繰り返し処理を自動化できます。
CLAUDE.mdが「Claudeへの指示」なら、hooksは「システムが必ず実行する自動処理の保証」です。

Claude Code hooksとは？自動化できる3つのこと

「hooksって難しそう」と思う方も多いはずです。
でも仕組み自体はシンプルで、「Claude Codeが〇〇をするときに自動的に△△を実行する」、それだけになります。

難しいのは最初の設定ファイルの書き方くらいで、構造さえわかればすぐ使えるはずです。

ここでは、以下の内容について詳しく解説します。

ワークフローを自動で動かす

hooksの最も基本的な使い方は、繰り返し作業の自動化です。たとえば「Claude Codeがファイルを編集したら、自動でprettierを実行する」という設定が数行のJSONで書けます。

ポイントは、Claudeの判断に委ねずに必ず実行される点です。
「フォーマットしておいて」と毎回頼む必要も、頼み忘れる心配もなくなります。

毎回手動でフォーマッターを実行していた手間がゼロになりました。私も最初にこれを設定したとき、「Claude Codeがこんなに便利になるのか」と素直に驚いたのを覚えています。
他にも「セッション開始時にGitブランチ情報をコンテキストに注入する」「実行ログを自動保存する」など、アイデア次第でいくらでも応用できます。

危険な操作にガードレールをかける

hooksの重要な役割として、LLMの判断に頼らず危険な操作を確実にブロックするという使い方があります。

Claude Codeに「慎重に操作して」と指示しても、LLMは必ずしも毎回同じ判断をするとは限りません。でもhooksでブロック設定を書いておけば、rm -rfや.envファイルの書き換えを決定論的に止められます。
チームのルールをコード（.claude/settings.json）に書いてGit管理すれば、全員に同じガードレールをかけられるのが強みです。

さらに、hooksによるブロックはbypassPermissionsモードでも機能します。どんな設定でもバイパスできないガードレールを作れる点が、CLAUDE.mdやpermissions設定との大きな違いです。

permissions側でどこまで許可を絞るかを決めたうえで、hooksを最後の砦として重ねると守りが厚くなります。許可と拒否の設計はClaude Codeの権限設定｜安全と手数の折衷ラインで整理しました。

ログや通知で作業を見える化する

Claude Codeに長時間タスクを任せていると、「いつ終わったか気づかなかった」という体験を一度はするはずです。Notificationイベントを使えば、Claudeが入力待ちになったタイミングでデスクトップ通知を飛ばせます。

他にも「実行されたBashコマンドをすべてログファイルに記録する」設定も簡単です。後からセッションを振り返るとき、「Claudeがどのコマンドを実行したか」が一覧で確認できます。

Claude Code hooksの使い方3つのステップ

「実際どうやって設定するの？」という疑問に答えます。Claude Code hooksの設定は、設定ファイルの場所さえ把握すれば、基本の設定は10分かかりません。

ここでは、以下の内容について詳しく解説します。

【ステップ1】設定ファイルを開く（場所の選び方）

hooksはJSON形式の設定ファイル（settings.json）に記述します。どこに置くかによって「誰に適用されるか」が変わります。用途に合わせて選びましょう。

最初の練習なら~/.claude/settings.jsonがおすすめです。全プロジェクトに適用されるので、一度設定すれば使い回せます。

ファイルがまだない場合は新規作成してください。
ディレクトリごと存在しないこともあるので、その場合は ~/.claude/ を作るところからになります。

すでに他の設定（permissions等）が書かれている場合は、ファイル全体を書き換えず既存の内容に"hooks"キーを追加する形で編集してください。

【ステップ2】hooksブロックをJSONで書く

設定ファイルを開いたら、hooksブロックを追加します。最初に動作確認しやすい「完了通知hook」を例にとります。macOSで「Claudeが入力待ちになったらデスクトップ通知を出す」最小設定はこうなります：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Linuxの場合はosascriptの部分をnotify-send 'Claude Code' 'Claude Code needs your attention'に置き換えてください。
Windows（WSL）だと通知の仕組みが環境によって変わります。
まずはターミナルにベル文字を鳴らす程度から試すと、動作確認がしやすいです。

すでにsettings.jsonに他のキーが存在する場合、hooksキーを兄弟として追加します：

{
  "permissions": { ... },
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "osascript -e '...'" }
        ]
      }
    ]
  }
}

【ステップ3】/hooksコマンドで動作を確認する

設定ファイルを保存したら、Claude Code上で/hooksと入力してください。登録されているhooksの一覧がイベント別に表示されます。設定したhookがリストに表示されていれば、読み込みは成功しています。

確認できたら実際に作業をしてhookが発火するかテストします。macOSで通知が表示されない場合は「システム設定 ＞ 通知」でScript Editorへの通知権限をオンにしてください。

ここまで動けば、あとは中身を差し替えていくだけです。
最初の1つが動いた瞬間に、hooksへの心理的なハードルはかなり下がりました。設定ファイルを触ること自体に慣れてしまえば、あとは応用のくり返しです。

/hooksメニューは読み取り専用です。
追加・変更・削除は設定JSONを直接編集するか、「settings.jsonのhooksを変更して」とClaude Codeに依頼する方法が使えます。

Claude Code hooksのJSON構造と書き方

基本の設定は書けても「matcherって何？」「exit codeをどう使うの？」と迷うことがあります。Claude Code hooksのJSONには決まった構造があるので、ここで整理しておきましょう。

ここでは、以下の内容について詳しく解説します。

イベント・matcher・commandの3層構造

hooksの設定はネストした3層構造になっています。最初は「どの括弧が何を意味するか」でつまずきやすいですが、構造がわかれば読めます。

{
  "hooks": {
    "PostToolUse": [        // ① イベント名：何のタイミングで発火するか
      {
        "matcher": "Edit|Write",  // ② matcher：どのツール呼び出し時か
        "hooks": [
          {
            "type": "command",     // ③ hookの種類（commandが基本）
            "command": "prettier --write ..."  // ④ 実行するコマンド
          }
        ]
      }
    ]
  }
}

matcherはそのhookを「どの操作のときに発火させるか」を絞るフィルターです。よく使うmatcherパターンはこちらです：

matcherを絞ることで「本当に必要なときだけhookを動かす」ことができます。typeは基本的に"command"（シェルコマンド実行）でOKです。他にも"http"（HTTPエンドポイントへのPOST）や"prompt"（LLMによる判断）が使えます。

exit codeで動作を制御する

hookスクリプトの終了コード（exit code）が、Claude Codeへの「返答」になります。シンプルな使い方ならこの3つを覚えておけば十分です。

exit 2でブロックするときは、stderrに理由を書いてください。その内容がClaudeにフィードバックとして渡るので、Claudeが状況を理解して別の方法を試みてくれます。以下はrm -rfを検知してブロックするシンプルな例です：

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')



if echo "$COMMAND" | grep -qE "rm -rf"; then
  echo "rm -rfは禁止されています。安全な削除方法を使ってください。" >&2
  exit 2
fi



exit 0

JSON出力でより細かく制御する

exit 2だけでなく、stdoutにJSONを出力することでより詳細な制御ができます。特にPreToolUseでは使い勝手がよいです。

「ブロックしてその理由をClaudeに伝える」場合、stdoutに以下のJSONを出力してexit 0を返します：

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "grepよりrgの方が高速です。rg を使ってください"
  }
}

permissionDecisionに指定できる値は"deny"（拒否）、"allow"（承認・インタラクティブ確認をスキップ）、"ask"（ユーザーに確認を促す）の3つです。

Claude Code hooksで使える主要イベント5つ

Claude Code hooksは20種類以上のイベントに対応しています。最初から全部覚える必要はありません。よく使う5つを押さえておくだけで、日常的な自動化はほぼカバーできます。

ここでは、以下の内容について詳しく解説します。

PreToolUse（ツール実行前に割り込む）

Claude Codeがツールを実行しようとするとき、その直前に発火するイベントです。exit 2を返せばツール実行をブロックできるため、ガードレールとして最も強力です。
matcherに"Bash"を指定すればBashコマンド実行前だけ、"Edit|Write"なら編集・書き込み前だけに絞れます。

「危険なコマンドを止める」「特定ファイルの書き換えを禁止する」「権限が必要な操作を自動承認する」などの使い方がメインです。

PostToolUse（ツール実行後に処理する）

ツールが正常に完了した直後に発火するイベントです。「実行後の後始末」に使います。自動フォーマット、ログ記録、出力の検証などが典型的なユースケースです。

重要な注意点として、PostToolUseはツールが動いた後なので「ロールバック」はできません。「止めたい」ならPreToolUseで事前に止める必要があります。
matcherに"Edit|Write"を設定すれば「ファイル編集のたびにprettierを実行」のような自動化が作れます。

Stop（Claude応答完了時に動かす）

Claudeがそのターンの応答を終えようとするときに発火します。「完了通知」や「やり残し確認」に使うイベントです。

exit 2を返すと「まだ作業が残っています」というフィードバックをClaudeに渡せるので、「テストが全部通るまで止まらない」という設定も作れます。ただし8回連続でブロックすると強制的に終了するため、無限ループ防止の仕組みが必要です（注意点の節で詳しく解説します）。

SessionStart（セッション開始時に準備する）

セッションが始まったとき、または/clearコマンドでリセットされたタイミングで発火するイベントです。stdoutに書いたテキストが自動でClaudeのコンテキストに追加されるため、「セッション開始時に毎回読ませたい情報」の注入に向いています。

matcher: "compact"を設定すると、Claude Codeのコンテキスト圧縮後だけに発火します。「圧縮で失われた重要なルールやコンテキストを再注入する」という使い方です。
私はこれを使って「このプロジェクトはBunを使う・npmは使わない」というルールを圧縮後に再注入していました。

Notification（通知タイミングをカスタムする）

Claude Codeが通知を送信するときに発火するイベントです。主に「入力待ち」や「権限確認」のタイミングになります。

macOSならosascript、Linuxならnotify-sendでデスクトップ通知が作れます。
コマンドさえ差し替えれば、Slackへの投稿や音を鳴らす形にも応用できました。

matcherを空にすると全通知タイミングで発火します。"idle_prompt"にすると「作業完了してユーザーの入力を待っているとき」だけに絞れました。

長時間タスクを回すときほど効いてくるイベントです。
裏で走らせて別の作業に移れるようになると、体感の生産性がはっきり変わります。

Claude Code hooksの実践レシピ5選

仕組みがわかったところで、Claude Code hooksをすぐ使えるレシピを3つ紹介します。コピペして自分の環境に合わせて調整してみてください。

ここでは、以下の内容について詳しく解説します。

【レシピ1】コード編集後に自動でフォーマット

Claude Codeがファイルを編集するたびにprettierを自動実行するレシピです。TypeScript・JavaScript・CSSなどのフォーマット一貫性を保てます。
jqコマンドが必要です（macOS: brew install jq、Ubuntu: apt-get install jq）。

.claude/settings.json（プロジェクト固有）または~/.claude/settings.json（全プロジェクト共通）に追加してください：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

jq -r '.tool_input.file_path'でhookに渡されたJSON（stdinで受け取ります）からファイルパスを取り出して、prettierに渡しています。プロジェクトにprettierが入っていれば、ファイル保存のたびにスタイルが整います。

【レシピ2】危険なBashコマンドをブロック

rm -rfや--forceオプションなど危険な操作をブロックするレシピです。プロジェクトの.claude/設定に入れておくとチームの安全ネットになります。
まずスクリプトファイルを作成します：

#!/bin/bash
# .claude/hooks/guard.sh



INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')



# ブロック対象のパターン
if echo "$COMMAND" | grep -qE "rm -rf|git push.*-f|git push.*--force"; then
  echo "危険なコマンドがブロックされました。" >&2
  echo "安全な代替方法を検討してください。" >&2
  exit 2
fi



exit 0

実行権限を付与します：

chmod +x .claude/hooks/guard.sh

.claude/settings.jsonに登録します：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard.sh"
          }
        ]
      }
    ]
  }
}

$CLAUDE_PROJECT_DIRはプロジェクトルートへのパスに自動で置き換わります。スクリプトへのパスに空白が含まれる場合に備えて、必ずダブルクォートで囲みましょう。

【レシピ3】完了時にデスクトップ通知

Claudeが入力待ちになったとき（作業完了時など）にデスクトップ通知を飛ばすレシピです。長時間タスクを他の作業と並行できるようになります。~/.claude/settings.jsonに追加すれば全プロジェクトで使えます。
macOSの場合：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Linuxの場合：

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

macOSで通知が表示されない場合は、ターミナルで一度osascript -e 'display notification "test"'を実行してから、「システム設定 ＞ 通知」でScript Editorへの通知権限をオンにしてください。

【レシピ4】Bashコマンドの実行ログを残す

Claude Codeが実行したBashコマンドを、すべてファイルに書き出しておくレシピです。あとから「あのとき何を流したんだっけ」を追えるようになります。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

hookの標準入力にはツールの入力内容がJSONで渡ってきます。jqで必要な部分だけ取り出してログに追記する形です。

jqが入っていない環境では動かないので、事前に確認しておいてください。
導入が難しい場合は、標準入力をそのまま丸ごと保存する形でも十分役に立ちます。

ログファイルが肥大化しないよう、日付でローテーションするか、定期的に消す仕組みも一緒に入れておくのがおすすめです。

【レシピ5】セッション開始時にブランチ情報を渡す

SessionStartイベントを使って、作業開始時に現在のGitブランチと直近のコミットをコンテキストへ流し込むレシピです。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"現在のブランチ: $(git branch --show-current) / 直近のコミット: $(git log -1 --oneline)\""
          }
        ]
      }
    ]
  }
}

SessionStartはstdoutの内容がそのままコンテキストに追加されます。毎回「今どのブランチ？」と聞かれる手間がなくなりました。

ブランチ名に作業内容を含める運用をしているなら、これだけで文脈がかなり伝わります。
Issue番号を入れているチームなら、そのまま関連情報の起点にもなります。

Claude Code hooksを使うときの注意点3つ

Claude Code hooksは便利ですが、実際に使うとはまるポイントがあります。
私自身がやらかした経験も含めて、先に共有しておきます。

PostToolUseではロールバックできない

PostToolUseはツールが完了した後に発火するため、「やっぱりキャンセル」ができません。ファイルはすでに変更されているし、コマンドはすでに実行されています。

私も最初、「PostToolUseでブロックすれば後から止められる」と思っていましたが、それは誤りでした。ブロックしたいならPreToolUseで事前に止める必要があります。
役割を整理するとこうなります：

この役割分担を意識するだけで、hookの設計がグッとシンプルになります。
迷ったら「止めたいのか、後で何かしたいのか」を自分に問い直すと決まります。

「後から止める」を実現したい場合は、PreToolUseで条件判定して弾く形に組み替えてください。
実行してしまってから戻す設計は、そもそも成立しません。

exit 2を誤用するとループが起きる

Stopイベントでexit 2を返し続けると、Claudeは「まだ作業が残っている」と判断して作業を続けます。しかし8回連続でブロックすると強制的に終了します。

これを防ぐには、stop_hook_activeフィールドを確認する処理をStopフックのスクリプトに入れます：

#!/bin/bash
INPUT=$(cat)



# Stopフックのループ防止（8回目で強制通過）
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0
fi



# 通常の確認処理をここに書く
# ...



exit 0

stop_hook_activeがtrueのときはexit 0で通過させることで、無限ループを防げます。このフィールドのチェックを入れ忘れると、Stopフックを使うたびに「8回ループして強制終了」という動作になります。これは正直、最初に気づかなくてかなりハマりました。

チーム共有と個人設定を分ける

hooksを設定するとき、「どのファイルに書くか」を意識しておかないと、後でチームメンバーとの摩擦が生まれます。
たとえば「自分はprettierを使うが、チームメンバーはbiomeを使っている」という場合、自動フォーマットのhookを.claude/settings.jsonにコミットすると他のメンバーのワークフローを壊してしまいます。

コミット対象（.claude/settings.json）に書くのは「チームで守るべきガードレール」だけにしてください。
個人の通知やフォーマットの好みは~/.claude/settings.jsonか.claude/settings.local.jsonに分けましょう。

どの設定をコミット対象にして、どこまで全員へ配るかの線引きはClaude Codeのチーム設定共有｜属人化を資産に変えようで整理しました。

使い分けの目安はこうなります。

Claude Code hooksに関するよくある質問

Q：Claude Code hooksとCLAUDE.mdの違いは何ですか？

A：CLAUDE.mdはClaudeへの「指示書」で、Claude自身が読んで判断します。一方hooksはClaude Codeのシステムが自動実行する「決定論的な処理」で、LLMの判断を介しません。
「毎回確実に実行したい処理」はhooks、「Claudeに方針を伝えたい内容」はCLAUDE.md、と使い分けるのが基本です。

Q：hooks設定が効いているか確認する方法は？

A：Claude Code上で/hooksと入力すると、登録されているhooksの一覧が確認できます。それでも動かない場合はclaude --debug-file /tmp/claude.logでClaudeを起動してデバッグログを確認してください。
どのhookがマッチしたか、終了コードやstderrの内容まで詳細に記録されています。

Q：Claude Code hooksはどのプランから使えますか？

A：Claude Code自体の利用には最低でもProプランへの加入が必要です（無料プランでは利用不可）。hooksはClaude Codeの設定機能なので、Claude Codeが使えるプランであれば追加料金なしで利用できます。
Claude Codeの始め方についてはClaude Codeの使い方まとめ｜初心者向けに詳しく解説を参考にしてください。

Q：Claude Code hooksが動かないときはどこを見ればいいですか？

まず /hooks で一覧に出ているかを確認してください。出ていなければJSONの構文エラーか、ファイルの置き場所が違っています。

一覧に出ているのに発火しない場合は、matcherの条件が狭すぎることが多いです。いったんmatcherを空文字にして全ツールで発火させ、そこから絞り込むと原因がつかめます。

Q：Claude Code hooksはチームで共有すべきですか？

ガードレール系は共有をおすすめします。.claude/settings.json に置いてGit管理すれば、全員に同じ制限がかかります。

一方、通知やフォーマッターの好みは人によって違うので、個人設定に置くほうが摩擦がありません。
共有するものと個人にとどめるものを分けておくと、あとから揉めずに済みます。

まとめ

Claude Code hooksは「設定ファイルにJSONを書くだけで、決まった処理を自動化できる」仕組みです。難しく見えますが、最初の通知hookを1つ動かすだけでも「こういうことか」とすぐに理解できます。

設定の進め方としては、まずNotificationイベントから試してみるのがおすすめです。次にPostToolUseの自動フォーマット、その次にPreToolUseのガードレールと、少しずつ試していきましょう。
一気に全部設定しようとするより、1つずつ動作確認しながら積み上げる方が確実です。

使いこなせるようになると、Claude Codeが単なる「便利なAIアシスタント」から「自分のワークフローに組み込まれた自動化ツール」に変わります。あなたのワークフローで一番繰り返している手作業は何でしょうか？そこから自動化を始めてみてください。

Claude Codeの活用方法をさらに深掘りしたい方は、Claude Code Skillsの使い方｜作り方と応用テクニックやClaude Codeでのターミナルの使い方｜苦手意識をなくそうも参考にしてみてください。

手を動かして覚えるのが一番早い一方で、腰を据えて学び直したくなる場面もあります。そのときの選択肢は、社会人におすすめの生成AI研修スクール｜スクール6校を比較にまとめてあります。