Claude Code hooksとは

Claude Code hooksは、Claude Codeの特定の実行タイミングで、あらかじめ設定した処理を自動実行する仕組みです。

たとえば、Claudeがファイルを編集した後にフォーマットを実行したり、Bashを実行する前に危険なコマンドを検査したりできます。

CLAUDE.mdは、Claudeに共有したい方針や前提知識を書くファイルです。一方、hooksは特定のタイミングで処理を発火させる設定です。

設計方針や前提知識はCLAUDE.mdに書き、実行したい処理はhooksに設定する、という使い分けができます。

フックイベント一覧

Claude Code hooksでは、実行タイミングごとに複数のフックイベントが用意されています。

以下は、2026年5月27日時点で公式リファレンスに掲載されているフックイベントです。

hooksの基本構造

hooksの設定は、3つの要素で構成されます。

1. どのイベントで処理を動かすか
2. matcherで対象を絞るか
3. どのtypeで処理するか

以下は、Claudeがファイルを編集した後にシェルスクリプトを実行する例です。

{
  "hooks": {
    // 1. どのイベントで動かすか
    "PostToolUse": [
      {
        // 2. どのツールを対象にするか
        "matcher": "Write|Edit",
        "hooks": [
          {
            // 3. どのtypeで処理するか
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

上記は説明用にコメントを入れた例です。実際のJSONでは、//から始まるコメント行を削除します。

matcherについて

matcherは、hookを発火させるツール名を指定する項目です。

たとえば、Bashを指定すると、ClaudeがBashを実行する時だけhookが発火します。

{
  "matcher": "Bash"
}

複数のツールを対象にする場合は、|でつなげます。

{
  "matcher": "Write|Edit"
}

正規表現も使えます。

{
  "matcher": "^Notebook"
}

MCPツールは、mcp__<server>__<tool>の形式で指定します。

{
  "matcher": "mcp__github__.*"
}

ツールの引数まで見て条件を分けたい場合は、hook handler側のifを使います。

{
  "hooks": {
    "PreToolUse": [
      {
        // Bashツールに絞る
        "matcher": "Bash",
        "hooks": [
          {
            // Bashの中でもgitコマンドだけを対象にする
            "if": "Bash(git *)",
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/check-git.sh"
          }
        ]
      }
    ]
  }
}

以下は、2026年5月27日時点で公式Tools referenceに掲載されている、hook matcherで指定できる主な組み込みツール名です。

typeについて

typeは、hookで実行する処理の種類です。

agentは、公式リファレンスで実験的な機能とされています。

設定ファイルの置き場所

hooksは、設定ファイルの置き場所によって適用範囲が変わります。

Claude Code hooksを試してみる

ここでは、5種類のtypeごとに簡単なサンプルを紹介します。

この記事のJSON例では、理解しやすいようにコメントを入れています。実際に.claude/settings.jsonへ保存する場合は、コメント行を削除します。

commandでシェルスクリプトを実行する

commandは、ローカルのコマンドやシェルスクリプトを実行するtypeです。

{
  "hooks": {
    // ファイル編集後に発火する
    "PostToolUse": [
      {
        // WriteまたはEditのときだけ実行する
        "matcher": "Write|Edit",
        "hooks": [
          {
            // ローカルのシェルスクリプトを実行する
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format.sh",
            "args": [],
            "timeout": 30
          }
        ]
      }
    ]
  }
}

httpで外部APIに通知する

httpは、hookの入力JSONをHTTP POSTで送信するtypeです。

{
  "hooks": {
    // Bash実行前に発火する
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            // 外部APIへPOSTする
            "type": "http",
            "url": "http://localhost:8080/hooks/pre-tool-use",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

mcp_toolでMCPツールを呼び出す

mcp_toolは、接続済みのMCPサーバーのツールを呼び出すtypeです。

{
  "hooks": {
    // ファイル編集後に発火する
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            // 接続済みMCPサーバーのツールを呼ぶ
            "type": "mcp_tool",
            "server": "my_server",
            "tool": "security_scan",
            "input": {
              "file_path": "${tool_input.file_path}"
            }
          }
        ]
      }
    ]
  }
}

promptでLLMに判定させる

promptは、Claudeモデルに単発の判定をさせるtypeです。

{
  "hooks": {
    // Claudeの応答完了時に発火する
    "Stop": [
      {
        "hooks": [
          {
            // Claudeモデルに判定させる
            "type": "prompt",
            "prompt": "作業が完了しているか判定してください。入力: $ARGUMENTS",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

agentでサブエージェントに確認させる

agentは、サブエージェントに確認作業を任せるtypeです。

{
  "hooks": {
    // Claudeの応答完了時に発火する
    "Stop": [
      {
        "hooks": [
          {
            // サブエージェントに確認させる
            "type": "agent",
            "prompt": "関連するテストが通っているか確認してください。入力: $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

おすすめの使い方

hooksは、Claude Codeの作業を補助する用途に向いています。

実装後にサブエージェントで影響範囲を確認する

PostToolUseとWrite|Editを組み合わせ、編集後にサブエージェントで影響範囲や追加テストの必要性を確認します。

危険なコマンドを実行前に止める

PreToolUseとBashのmatcherを組み合わせると、Bash実行前にコマンドを検査できます。

編集後にフォーマットやlintを実行する

PostToolUseとWrite|Editを組み合わせると、ファイル編集後に処理を実行できます。

長時間作業の完了を通知する

StopやNotificationを使うと、作業完了や権限確認を外部に通知できます。

MCPツールの利用を記録する

MCPツールは、mcp__<server>__<tool>形式の名前でmatcherに指定できます。

hooks設定で気をつけること

hooksは便利ですが、設定内容によっては開発環境やセキュリティに影響します。

実行権限に注意する

command hooksは、ユーザーの環境でコマンドを実行します。

JSONにコメントは書けない

この記事のJSON例では、理解しやすいようにコメントを入れています。実際に.claude/settings.jsonへ保存する場合は、コメント行を削除します。

matcherが効かないイベントがある

UserPromptSubmit、PostToolBatch、Stop、TeammateIdle、TaskCreated、TaskCompleted、WorktreeCreate、WorktreeRemove、CwdChangedはmatcher非対応です。

typeによって待ち時間が変わる

外部API連携、テスト実行、サブエージェント確認などでは、timeoutを明示すると待ち時間を管理しやすくなります。

agent hooksは実験的な機能として扱う

agent hooksは、公式リファレンスで実験的な機能とされています。

secretsの扱いに注意する

トークンやAPIキーをリポジトリに含めないようにし、.claude/settings.local.jsonや環境変数を使って分離します。

まとめ

Claude Code hooksは、Claude Codeの作業を安全に、安定して進めるための自動化機能です。

イベント、matcher、typeを組み合わせることで、ファイル編集後の整形、危険コマンドの検査、作業完了通知、MCPツールの監査などを実現することができます。

まずは、ファイル編集後にフォーマットを実行するような小さなhookから始めてみましょう。