Claude Code のフック（hooks）機能の使い方

Claude Code を使っていて、「作業が終わったら自動で何かしてほしい」と思ったことはないですか？

フック（hooks）機能を使えば、Claude Code の特定のタイミングにコマンドを自動で走らせることができます。通知を出したり、ログを記録したり、ちょっとした演出を入れたり。アイデア次第で可能性は広がります。

この記事では、フックの仕組みから実際の使い方まで、順を追って説明していきます。

フックとは何か

フック（hooks）は、Claude Code の特定のイベントが発生したときに、任意のコマンドを自動で実行できる仕組みです。

たとえば、以下のような使い方ができます。

• 作業完了時に通知音を鳴らす
• ツール実行のたびにログを記録する
• 一定確率でユニークなメッセージを表示させる

フックで実行したコマンドの 標準出力（stdout）はターミナルには表示されず、Claude のコンテキストに注入されます。これが大事なポイントです。ターミナルに出力したい場合は、stderr に出力するか別の方法を取る必要があります。

設定方法

フックの設定は settings.json に記述します。場所は2つあります。

基本的な構造はこうなります。

{
  "hooks": {
    "イベント名": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "実行するコマンド"
          }
        ]
      }
    ]
  }
}

matcher は対象ツール名などでフィルタリングするための項目です。空文字にするとすべてのイベントに反応します。

主なイベント一覧

用途によって使い分けましょう。「何かが終わったらやりたい」なら Stop や PostToolUse、「セッション開始時に決まった処理をしたい」なら SessionStart が便利です。

終了コードの意味

フックで実行したコマンドの 終了コード（exit code） によって、Claude の動作をコントロールすることもできます。

たとえば PreToolUse フックで終了コード 2 を返せば、そのツールの実行を止めることができます。自動実行の安全弁として使えますね。

実用例：10% の確率で作業内容にちなんだメッセージを注入する

実際にやってみましょう。作業が完了したとき（Stop イベント）に、10% の確率でメッセージを Claude のコンテキストに注入する仕組みを作ります。

シェルスクリプトを用意する

まず、実行したい処理をシェルスクリプトに書きます。

#!/bin/bash
# 10%の確率でメッセージを注入する
if [ $((RANDOM % 10)) -eq 0 ]; then
  echo "作業が完了しました。今の作業内容にちなんだひとことを添えてください。"
fi

RANDOM は bash の組み込み変数で、0〜32767 のランダムな整数を返します。% 10 で余りを取ると 0〜9 の値になるので、ちょうど 0 になる確率が 10% になります。

ここがポイントです。echo で出力した内容は Claude のコンテキストに送られます。つまり Claude はその内容を「自分への指示」として受け取ります。ターミナルには何も表示されません。

スクリプトをたとえば以下の場所に保存します。

~/.claude/hooks/my-hook.sh

settings.json に設定する

次に、このスクリプトを Stop イベントで呼び出すよう設定します。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "bash /home/yourname/.claude/hooks/my-hook.sh"
          }
        ]
      }
    ]
  }
}

Windows 環境では bash D:/path/to/hooks/my-hook.sh のように記述します。

これだけです。設定を保存すれば、次回から Claude が応答を終えるたびに、1割の確率でスクリプトが動きます。

stdout はコンテキストに注入される

改めて強調しておきたいのが、この仕様です。

フックスクリプトの stdout（標準出力）は、Claude のコンテキストに注入される

つまり echo で出力した内容が、そのまま Claude への隠しメッセージになります。Claude はそれを読んで、必要があれば追加のアクションを取ります。

逆に言えば、ターミナルに表示したい内容があれば stderr に出力する（echo "..." >&2）のが正しい使い方です。

この仕様を理解しておくと、フックの設計がぐっとやりやすくなります。

CLAUDE.md がすっきりする

フックを導入すると、うれしい副作用があります。それは CLAUDE.md に書いていた繰り返し指示を減らせる ことです。

たとえば、こんな指示を CLAUDE.md に書いていた人もいるかもしれません。

• 「作業が完了したら必ず〇〇してください」
• 「ファイルを書き込む前に必ずバックアップを確認してください」
• 「セッション開始時には今日の日付を確認してください」

これらは「毎回 Claude に言い聞かせる」形の指示です。フックを使えば、こうした手順を自動化できます。CLAUDE.md に書かなくても、決まった処理が確実に動くようになります。

結果として、CLAUDE.md はプロジェクトの目的・構成・判断基準の説明に集中できます。「自動化できる手順はフックに任せる、人間だけが決められるルールは CLAUDE.md に書く」という分担が整うと、設定全体がぐっと読みやすくなります。

まとめ

フック機能は、Claude Code の動作をカスタマイズする強力な手段です。単純な通知から、条件付きのブロック処理まで、アイデア次第で幅広く使えます。

まずは Stop イベントにシェルスクリプトを1本つなぐところから、試してみましょう！

フックの設定は Claude Code に作ってもらえる

「シェルスクリプトを書くのはちょっとハードルが高い…」と感じた方、大丈夫です。フックの設定ファイルもスクリプトも、Claude Code 自身に作ってもらえます。

たとえばこう頼んでみましょう。

「作業完了時に10%の確率でAIエージェントが俳句を詠むフックを作って」

これだけで、Claude Code はシェルスクリプトの中身から settings.json への設定記述まで、まとめて用意してくれます。自分でゼロから書く必要はありません。

フックは「仕組みを理解した人だけのもの」ではありません。やりたいことを言葉で伝えれば、Claude Code が形にしてくれます。まずは気軽に頼んでみるところから始めてみましょう。