Claude Code Hooks
Claude Code のライフサイクルイベントに処理を差し込む仕組み。シェルスクリプトを特定のタイミングで自動実行できる。
ライフサイクルイベント一覧
| イベント | タイミング |
|---|---|
SessionStart | セッション開始時 |
Stop | Claude が応答を完了したとき |
PreToolUse | ツール実行の直前 |
PostToolUse | ツール実行の直後 |
SubagentStop | サブエージェント完了時 |
UserPromptSubmit | ユーザーがプロンプト送信直前 |
設定方法
/hooks コマンドで対話設定するか、settings.json に直接記述する。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "npm run format" }]
}
]
}
}シェルスクリプトを .sh ファイルに切り出してコマンドとして呼ぶのが推奨パターン。
終了コードによる制御
PreToolUse フックで特定の終了コードを返すとツール実行をブロックできる。
| 終了コード | 動作 |
|---|---|
0 | 正常通過 |
2 | ツール実行をブロック |
主なユースケース
- SessionStart — 依存関係インストール（
npm install自動実行） - Stop — 完了通知音・ログ記録
- PostToolUse（Write/Edit） — フォーマッター・リンターの自動実行
- UserPromptSubmit — プロンプトへのコンテキスト自動付与、機密情報フィルタリング
マッチャー
ワイルドカードでツール名を絞り込める。
"matcher": "Bash" // Bash ツールのみ
"matcher": "Write|Edit" // Write または Edit
"matcher": "*" // 全ツール環境変数
フック実行時にプロジェクト情報（プロジェクト名・ファイルパスなど）が環境変数として渡される。これを使ったログ記録や条件分岐が可能。