Hooks システム
Hooks で Claude Code の動作をカスタマイズ — 自動フォーマット、セキュリティブロック、通知プッシュなど
Hooks システム¶
Hooks を使うと、Claude Code の重要なライフサイクルポイントにカスタムロジックを挿入できます。例えば、コードの自動フォーマット、危険なコマンドのブロック、通知の送信などが可能です。
コアコンセプト¶
各 Hook は 3 つの要素で構成されます：
-
イベント：トリガーのタイミング（例：
PreToolUse— ツール実行前） -
マッチャー：オプションのツール名フィルター（例：
BashやWriteのみにマッチ） -
ハンドラー：Shell コマンド、プロンプト、またはサブエージェント
主なイベント¶
| イベント | トリガーのタイミング | ブロック可否 | 典型的なユースケース |
|---|---|---|---|
PreToolUse |
ツール実行前 | 可（exit code 2） | セキュリティブロック、ファイル保護 |
PostToolUse |
ツール実行後 | 不可 | 自動 lint/フォーマット |
Notification |
Claude が通知を送信時 | 不可 | Slack/チャットツールへのアラート |
UserPromptSubmit |
ユーザーがプロンプトを送信時 | 可 | コンテキストの拡張 |
Stop |
Claude がレスポンスを完了時 | 不可 | 品質チェック、要約 |
SessionStart |
セッション開始時 | 不可 | 環境の初期化 |
設定方法¶
.claude/settings.json（プロジェクトレベル）または ~/.claude/settings.json（ユーザーレベル）に追加します：
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "prettier --write $FILEPATH"
}
]
}
]
}
}
実用的な例¶
1. ファイル保存後の自動フォーマット¶
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npx prettier --write $FILEPATH"
}
]
}
]
}
}
2. 危険な Shell コマンドのブロック¶
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo $TOOL_INPUT | grep -qE 'rm -rf|sudo|git push --force' && exit 2 || exit 0"
}
]
}
]
}
}
exit 2でツールの実行をブロックし、exit 0で続行を許可します。
3. 機密ファイルの読み取りを防止¶
{
"hooks": {
"PreToolUse": [
{
"matcher": "Read",
"hooks": [
{
"type": "command",
"command": "echo $TOOL_INPUT | grep -qE '\\.env|credentials|secret' && exit 2 || exit 0"
}
]
}
]
}
}
4. タスク完了時に通知を送信¶
{
"hooks": {
"Notification": [
{
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"$NOTIFICATION_MESSAGE\" with title \"Claude Code\"'"
}
]
}
]
}
}
入出力メカニズム¶
-
Hook スクリプトは stdin 経由で JSON データ（
session_id、tool_name、tool_inputを含む）を受け取ります -
環境変数：
$FILEPATH、$TOOL_INPUT、$NOTIFICATION_MESSAGEなど -
PreToolUse の exit code：
0= 許可、2= ブロック
デバッグのヒント¶
-
Ctrl+Oを押して verbose モードを有効にし、Hook の stdout/stderr 出力を確認 -
Hook スクリプトをテストする前に、ターミナルで手動実行してロジックが正しいか確認
注意事項¶
-
Hook スクリプトの実行時間が長すぎると、Claude Code のインタラクションがブロックされます
-
プロジェクトレベルの Hooks はユーザーレベルの Hooks よりも優先されます
-
エンタープライズ版では
managed-settings.jsonを使って組織全体にセキュリティ Hooks を強制できます
次のステップ¶
-
Skills のヒント でより高度な拡張方法を確認
-
MCP サーバー で外部ツール連携を確認
-
CLI のヒント でコマンドラインの使い方のコツを確認