Claude Code フックは、Claude Codeのライフサイクルの様々な時点で実行されるユーザー定義のシェルコマンドです。フックは、Claude Codeの動作に対する決定論的な制御を提供し、LLMが実行を選択することに依存するのではなく、特定のアクションが常に実行されることを保証します。

フックのリファレンスドキュメントについては、フックリファレンスを参照してください。

フックの使用例には以下が含まれます：

  • 通知: Claude Codeがあなたの入力や何かを実行する許可を待っているときの通知方法をカスタマイズします。
  • 自動フォーマット: ファイル編集後に.tsファイルでprettierを実行、.goファイルでgofmtを実行など。
  • ログ記録: コンプライアンスやデバッグのために実行されたすべてのコマンドを追跡・カウントします。
  • フィードバック: Claude Codeがあなたのコードベース規約に従わないコードを生成したときに自動フィードバックを提供します。
  • カスタム権限: 本番ファイルや機密ディレクトリへの変更をブロックします。

これらのルールをプロンプト指示ではなくフックとしてエンコードすることで、提案を実行が期待されるたびに実行されるアプリレベルのコードに変換します。

フックを追加する際は、フックのセキュリティへの影響を考慮する必要があります。フックは現在の環境の認証情報でエージェントループ中に自動的に実行されるためです。 例えば、悪意のあるフックコードはあなたのデータを流出させる可能性があります。フックを登録する前に、常にフックの実装を確認してください。

完全なセキュリティベストプラクティスについては、フックリファレンスドキュメントのセキュリティ考慮事項を参照してください。

​
フックイベント概要

Claude Codeは、ワークフローの異なる時点で実行される複数のフックイベントを提供します：

  • PreToolUse: ツール呼び出しの前に実行（ブロック可能）
  • PostToolUse: ツール呼び出し完了後に実行
  • Notification: Claude Codeが通知を送信するときに実行
  • Stop: Claude Codeが応答を終了するときに実行
  • SubagentStop: サブエージェントタスクが完了するときに実行

各イベントは異なるデータを受け取り、Claudeの動作を異なる方法で制御できます。

​
クイックスタート

このクイックスタートでは、Claude Codeが実行するシェルコマンドをログに記録するフックを追加します。

​
前提条件

コマンドラインでのJSON処理のためにjqをインストールしてください。

​
ステップ1: フック設定を開く

/hooks スラッシュコマンドを実行し、PreToolUseフックイベントを選択します。

PreToolUseフックはツール呼び出しの前に実行され、Claudeに何を異なって行うべきかのフィードバックを提供しながらそれらをブロックできます。

​
ステップ2: マッチャーを追加

+ Add new matcher…を選択して、Bashツール呼び出しのみでフックを実行します。

マッチャーにBashと入力します。

すべてのツールにマッチするには空文字列""を使用します。*文字は単独では有効なマッチャーではありません。

​
ステップ3: フックを追加

+ Add new hook…を選択し、このコマンドを入力します：

jq -r '"\(.tool_input.command) - \(.tool_input.description // "No description")"' >> ~/.claude/bash-command-log.txt

​
ステップ4: 設定を保存

ストレージ場所として、ホームディレクトリにログを記録するためUser settingsを選択します。このフックは現在のプロジェクトだけでなく、すべてのプロジェクトに適用されます。

その後、REPLに戻るまでEscを押します。フックが登録されました！

​
ステップ5: フックを確認

再度/hooksを実行するか、~/.claude/settings.jsonをチェックして設定を確認します：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

​
ステップ6: フックをテスト

Claudeにlsのような簡単なコマンドを実行するよう依頼し、ログファイルを確認します：

cat ~/.claude/bash-command-log.txt

以下のようなエントリが表示されるはずです：

ls - Lists files and directories

​
その他の例

完全な実装例については、公開コードベースのbash command validator exampleを参照してください。

​
コードフォーマットフック

編集後にTypeScriptファイルを自動的にフォーマット：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "if echo '$(.tool_input.file_path)' | grep -q '\\.ts$'; then npx prettier --write '$(.tool_input.file_path)'; fi"
          }
        ]
      }
    ]
  }
}

​
カスタム通知フック

Claudeが入力を必要とするときにデスクトップ通知を取得：

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

​
ファイル保護フック

機密ファイルへの編集をブロック：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|MultiEdit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json, sys; data=json.load(sys.stdin); path=data.get('tool_input',{}).get('file_path',''); sys.exit(2 if any(p in path for p in ['.env', 'package-lock.json', '.git/']) else 0)\""
          }
        ]
      }
    ]
  }
}

​
さらに学ぶ

  • フックのリファレンスドキュメントについては、フックリファレンスを参照してください。
  • 包括的なセキュリティベストプラクティスと安全ガイドラインについては、フックリファレンスドキュメントのセキュリティ考慮事項を参照してください。
  • トラブルシューティング手順とデバッグ技術については、フックリファレンスドキュメントのデバッグを参照してください。