Claude Code hooks設定ガイド——完了通知・コマンドガード・ログ記録の実装

Claude Code をスクリプトから呼び出してバッチ処理していると、「ツール実行の前後で何かを確認したい」「生成が終わったら通知がほしい」という場面が出てきます。それを settings.json だけで解決するのが hooks 機能です。シェルコマンドをライフサイクルの各タイミングに登録するだけで、コマンドのガード・ログ記録・完了通知が実現できます。この記事では、フックの仕組み・設定の書き方・すぐ使える3パターンを順番に説明します。

hooks とは何か

hooks は、Claude Code がツールを使ったり応答を完了したりするタイミングにシェルコマンドを差し込む仕組みです。Claude 本体へのプロンプト指示とは別に、設定ファイルに登録したコマンドを Claude Code のプロセスが直接実行します。

できることを整理すると：

• ツール実行前にコマンドを検査して 止める（危険な操作を防ぐ）
• ツール実行後に ログ を記録する
• 生成完了時に デスクトップ通知 を送る
• 外部 API や Webhook を呼び出す

「Claude に頼まなくてもコードで制御できる」という性質上、自動化スクリプトや CI 的な使い方と相性が良いです。

設定ファイルの場所と書き方

フックは settings.json の hooks キーに書きます。スコープは2段階あります。

両方に書いた場合は両方がマージされて実行されます。一方が他方を上書きするわけではありません。個人的な通知設定はユーザースコープに、チームで統一したいガードルールはプロジェクトスコープに置くと整理しやすいです。

基本の構造：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/guard_bash.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' '処理完了'"
          }
        ]
      }
    ]
  }
}

各フィールドの意味：

• matcher — ツール名に対する正規表現。"Bash" なら Bash ツールのみ、".*" なら全ツールが対象。Stop など非ツールイベントには不要。
• type — 現在は "command" のみ対応（執筆時点）。
• command — 実行するシェルコマンドまたはスクリプトのパス。スクリプトを指定する場合は事前に chmod +x が必要です。

フックの種類と受け取る JSON

公式ドキュメントが定義するイベントは以下の通りです（執筆時点）。

フックコマンドは標準入力（stdin）から JSON を受け取ります。PreToolUse のペイロード例：

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "git push origin main",
    "description": "変更をリモートにプッシュ"
  }
}

PostToolUse では上記に加えて tool_response フィールドが付きます。JSON の構造はバージョンによって変わる可能性があるため、受け取った値は jq の // "" や Python の .get() など安全な方法でパースしてください。

PreToolUse の終了コードとブロック制御

PreToolUse フックでは、終了コードでツールの実行可否を制御できます。

終了コード 2 のとき、stdout/stderr に書いたメッセージが Claude の文脈に渡ります。「このコマンドはポリシー違反です」と出力しておけば、Claude がその理由を読んで対応を変えることが期待できます。

PostToolUse・Stop・Notification では終了コードによるブロックはなく、スクリプトが失敗してもログに記録されるだけで処理は続行されます。

実用例3パターン

パターン1: 危険なコマンドをブロックする

jq コマンドが必要です（未導入なら sudo apt install jq で入ります）。

#!/usr/bin/env bash
# ~/.claude/hooks/guard_bash.sh

input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')

if echo "$cmd" | grep -qE '(rm -rf /|dd if=|mkfs|shutdown|reboot)'; then
  echo "ポリシー違反のコマンドを検出しました: $cmd" >&2
  exit 2
fi

exit 0

chmod +x ~/.claude/hooks/guard_bash.sh を実行してから settings.json の PreToolUse に登録します。rm -rf / などのパターンを Claude が実行しようとすると、フックが止めてメッセージをフィードバックします。

パターン2: 生成完了をデスクトップ通知する

Linux（libnotify-bin 導入済み）の場合：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send '✅ Claude Code' '処理完了'"
          }
        ]
      }
    ]
  }
}

macOS では notify-send の代わりに次のコマンドを使ってください：

osascript -e 'display notification "完了" with title "Claude Code"'

バッチ処理を投げて別の作業をしているときに、完了を見逃さなくなります。

パターン3: ツール使用をファイルにログ記録する

#!/usr/bin/env bash
# ~/.claude/hooks/tool_logger.sh
input=$(cat)
echo "$(date '+%Y-%m-%d %H:%M:%S') $input" >> ~/.claude/tool_usage.log
exit 0

settings.json の PostToolUse に登録：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/tool_logger.sh"
          }
        ]
      }
    ]
  }
}

全ツールの入出力が ~/.claude/tool_usage.log に追記されます。バッチ処理の途中で何が起きたかを後から確認するのに使えます。

まとめ

Claude Code の hooks を設定する手順をまとめます。

1. ~/.claude/settings.json（またはプロジェクトの .claude/settings.json）を開く
2. hooks キーにイベント名・matcher・command を書く
3. スクリプトを使う場合は chmod +x する
4. claude を起動して動作を確認する

最初に試すなら Stop フックへの完了通知登録が最もシンプルです。settings.json に数行追加するだけで「バッチが終わったら教えて」という需要をすぐ満たせます。安定したら PreToolUse のガードスクリプトを足していく、という順番が壊しにくい進め方です。

サブエージェントを並列で走らせる場合は SubagentStop イベントも合わせて使うと、個々の完了タイミングを捕まえられます。Task ツールの仕組みについては「Claude Code Task tool のサブエージェント並列実行——仕組みと上限の実際」も参考にしてください。