Hooks 完全リファレンス（全パターン解説）

Hooks とは

Claude CodeのHooksは、特定のイベントが発生したタイミングで自動的にスクリプトを実行する機能です。「Claudeがファイルを編集する前に確認する」「コミット前にlintを走らせる」「作業完了後にログを保存する」といった自動化が可能になります。

設定は ~/.claude/settings.json（グローバル）または .claude/settings.json（プロジェクト）に記述します。

※Hooks: Claude Codeの特定の操作（ツール実行前後など）に独自のシェルコマンドを自動実行できる設定機能。※コミット: Gitでファイルの変更を履歴として記録する操作。

Hook の種類

Claude Codeには現在4種類のHookがあります。

Hook名	発火タイミング	主な用途
`PreToolUse`	ツール実行前	バリデーション・確認・ブロック
`PostToolUse`	ツール実行後	ログ記録・後処理
`Notification`	通知発生時	作業完了の通知
`Stop`	Claudeの停止時	セッション終了処理

設定の基本構造

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "ツール名のパターン",
        "hooks": [
          {
            "type": "command",
            "command": "実行するシェルコマンド"
          }
        ]
      }
    ]
  }
}

PreToolUse Hook

ツールが実行される前に発火します。コマンドの終了コードによって動作が変わります。

終了コード	動作
`0`	ツールの実行を許可（続行）
`1`	ツールの実行をブロックし、出力をClaude に伝える

使用できるツール名

matcher に指定できるツール名：

Bash — シェルコマンド実行
Edit — ファイル編集
Write — ファイル書き込み
Read — ファイル読み込み
Glob — ファイル検索
Grep — テキスト検索
mcp__* — MCPツール（ワイルドカード使用可）

環境変数でコンテキストを取得する

PreToolUse Hookでは、以下の環境変数でコンテキストを取得できます：

# ツールの入力パラメータ（JSON文字列）
echo $CLAUDE_TOOL_INPUT

# 現在のプロジェクトディレクトリ
echo $CLAUDE_PROJECT_DIR

# セッションID
echo $CLAUDE_SESSION_ID

Bash ツール用の詳細情報

# 実行しようとしているコマンド
COMMAND=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.command')
echo "実行コマンド: $COMMAND"

Edit / Write ツール用の詳細情報

# 編集対象のファイルパス
FILE_PATH=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.file_path')
echo "対象ファイル: $FILE_PATH"

※コンテキスト: Claudeが一度に記憶・参照できる会話・コードの範囲。上限を超えると古い情報が失われる。※環境変数: APIキーやデータベース接続情報など、コードに直接書きたくない値をOSやサーバーに設定する仕組み。※MCP: Model Context Protocol の略。Claude Codeと外部ツール（GitHub・Supabaseなど）を接続するための標準プロトコル。

PostToolUse Hook

ツールが実行された後に発火します。戻り値に関わらずログ記録や後処理に使います。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$(date): ファイルが編集されました\" >> ~/.claude/edit-log.txt"
          }
        ]
      }
    ]
  }
}

PostToolUse では追加の環境変数が使えます：

# ツールの実行結果（JSON文字列）
echo $CLAUDE_TOOL_OUTPUT

# 実行が成功したか（"true"/"false"）
echo $CLAUDE_TOOL_SUCCESS

Notification Hook

Claude Codeからの通知が発生したときに実行されます。長時間の作業完了をデスクトップ通知するのに使います。

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' '${CLAUDE_NOTIFICATION_MESSAGE}'"
          }
        ]
      }
    ]
  }
}

Stop Hook

Claudeがセッションを終了するときに発火します。作業ログの保存や後片付けに使います。

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"セッション終了: $(date)\" >> ~/.claude/sessions.log"
          }
        ]
      }
    ]
  }
}

matcher のパターン

完全一致

{ "matcher": "Bash" }      // Bashツールのみ
{ "matcher": "Edit" }      // Editツールのみ

ワイルドカード

{ "matcher": "mcp__*" }    // 全MCPツール
{ "matcher": "" }          // 全てのツール（空文字）

正規表現

{ "matcher": "Edit|Write" }   // EditまたはWrite

よくある設定の例

複数のHookをチェーンする

一つのイベントに複数のコマンドを設定できます：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/.claude/hooks/check-command.sh"
          },
          {
            "type": "command",
            "command": "/home/user/.claude/hooks/log-command.sh"
          }
        ]
      }
    ]
  }
}

プロジェクト固有のHookとグローバルHookの使い分け

~/.claude/settings.json — 全プロジェクトで使うルール（危険コマンドのブロックなど）
.claude/settings.json — このプロジェクトだけのルール（特定のlintコマンドなど）