Claude Code Hook Debug Cheatsheet — hookが動かないときの診断手順

hookを設定したのに動作しない場合の診断フロー。

1. settings.jsonの構文チェック

jq . ~/.claude/settings.json
# エラーが出たらJSON構文が壊れている

2. hookスクリプトに実行権限があるか

ls -la ~/.claude/hooks/
# -rwxr-xr-x なら OK
# -rw-r--r-- なら chmod +x が必要
chmod +x ~/.claude/hooks/*.sh

3. hookスクリプトが単体で動くか

# PreToolUse hookの場合
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | bash ~/.claude/hooks/your-hook.sh
echo $?
# exit 0 = 許可, exit 2 = ブロック

4. jqがインストールされているか

which jq
# 見つからない場合:
# macOS: brew install jq
# Ubuntu: sudo apt install jq
# Windows: winget install jqlang.jq

5. イベントタイプが正しいか

イベント	発火タイミング
PreToolUse	ツール実行前
PostToolUse	ツール実行後
UserPromptSubmit	ユーザーがEnter
PreCompact	compaction前
Stop	セッション終了時
Notification	通知送信時
SessionStart	セッション開始時

6. matcherが正しいか

{
  "matcher": "Bash",  // ← ツール名と完全一致
  "hooks": [...]
}

よくある間違い: "matcher": "bash" (小文字) → 動かない。"Bash" (大文字) が正しい。

ツール名一覧: Bash, Read, Write, Edit, Glob, Grep, Agent, WebSearch, WebFetch

7. exit codeの意味

exit code	意味
0	許可（何もしない）
2	ブロック（ツール実行を中止）
1	エラー（ツール実行は続行）

よくある間違い: exit 1 でブロックしようとする → ブロックされない。exit 2 を使う。

8. Claude Codeを再起動したか

settings.jsonの変更はClaude Code再起動後に反映される。

655個の安全hookを一括設定: npx cc-safe-setup hookの設定ミスを検出: https://yurukusa.github.io/cc-safe-setup/settings-validator.html トークン消費を半分にする: https://yurukusa.github.io/cc-safe-setup/token-book.html (¥2,500)

yurukusa/hook-debug-cheatsheet.md

Select an option

No results found