Claude Codeを始めたばかりの方へ: hookを設定したけど動いている気配がない、という方のためのトラブルシューティングガイドです。1つずつ確認すれば、ほとんどの問題は解決します。

「hookを設定したのに動かない」。Claude Code hookの一番よくある問題だ。

この記事では、hookが動かない原因を5分以内に特定する方法を紹介する。

まず試す: --doctor

npx cc-safe-setup --doctor

13項目を自動チェックする:

jqがインストールされているか
settings.jsonが存在し、有効なJSONか
hooks セクションが設定されているか
各hookスクリプトが存在するか
実行権限があるか
shebangがあるか（スクリプト先頭の#!/bin/bashのこと。OSに「このファイルをどのプログラムで実行するか」を伝える行）
空入力でエラーにならないか

ほとんどの問題はこれで見つかる。

よくある原因ベスト5

1. jqがない

:::details 初心者向け: jqとは
jqは、JSON形式のデータを読み取り・加工するためのコマンドラインツールです。hookはClaude Codeから「今から何をしようとしているか」という情報をJSON形式で受け取ります。jqがないとその情報を読めないので、hookは何もできません。
:::

:::details 初心者向け: stdinとは
stdin（標準入力）とは、プログラムが外部からデータを受け取る入り口のことです。郵便受けのようなもので、Claude Codeが「今からこのコマンドを実行しようとしています」という情報をJSON形式で郵便受けに入れ、hookスクリプトがそれを取り出して中身を確認します。
:::

hookはstdinからJSONを受け取り、jqでパースする。jqがないと何も動かない。

# 確認
which jq

# インストール
brew install jq      # macOS
apt install jq       # Ubuntu/Debian
choco install jq     # Windows

2. スクリプトに実行権限がない

:::details 初心者向け: 実行権限とは
Linux/macOSでは、ファイルに「このファイルはプログラムとして実行できます」という許可（実行権限）を明示的に付ける必要があります。実行権限がないと、スクリプトの中身が正しくても「Permission denied」で動きません。
:::

# 確認
ls -la ~/.claude/hooks/

# 修正
chmod +x ~/.claude/hooks/*.sh

3. settings.jsonのJSON構文エラー

手動で編集してカンマを忘れた、など。JSONは文法に厳格で、カンマ1つ忘れただけでファイル全体が読めなくなる。日本語の文章で句読点を忘れても意味は通じるが、JSONではそうはいかない。

# 確認
python3 -m json.tool ~/.claude/settings.json

# エラーが出たら
npx cc-safe-setup --uninstall
npx cc-safe-setup

4. Claude Codeを再起動していない

hookはClaude Code起動時に読み込まれる。settings.jsonを変更したら再起動が必要。

5. Windowsでの起動オーバーヘッド

Windows環境でPythonスクリプトのhookを使っている場合、Pythonの起動に200-500msかかる。hookにタイムアウトがあるため、軽いスクリプト（bash）は100%発火するのに、重いスクリプト（Python）は18%しか発火しないという現象が起きる。

対策: Pythonの代わりにbashを使う。

#!/bin/bash
# Pythonの代わり
INPUT=$(cat)
VALUE=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
# ... bashで処理

hookの発火を確認する方法

#!/bin/bash
# hook-test.sh — hookに追加して発火を記録
echo "[$(date)] Hook fired: $0" >> /tmp/hook-fire.log

これをhookの先頭に追加して、Claude Codeでコマンドを実行し、/tmp/hook-fire.logを確認する。

正しいsettings.json構造

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/my-hook.sh"
          }
        ]
      }
    ]
  }
}

よくある間違い:

"type": "command" を忘れる
"matcher" のスペルミス
hookの配列構造が間違っている（hooks内にhooks）

まとめ

# 1. 診断
npx cc-safe-setup --doctor

# 2. 問題なければ再起動
# Claude Codeを終了して再起動

# 3. それでもダメなら再インストール
npx cc-safe-setup --uninstall
npx cc-safe-setup

hookが動く状態を確認してから設定を追加していくのが確実。

関連記事

Anthropic公式「Skills完全ガイド」 — SKILL.mdの設計パターン
PreToolUseフックで危険な操作を自動ブロックする — hookの具体的な実装
108時間無人で走らせて起きた全事故と安全装置 — 長時間運用の実事故

「AIに任せて大丈夫なのか」という不安を持ったまま800時間使い続けた記録は非エンジニアがClaude Codeを800時間走らせた——失敗と学びの全記録（¥800・第2章まで無料）に書いた。

📖 トークン消費に困っているなら → Claude Codeのトークン消費を半分にする——800時間の運用データから見つけた実践テクニック（¥2,500・はじめに+第1章無料）

⚠ Opus 4.7緊急情報（2026年4月）
auto modeの安全分類器がOpus 4.6にハードコードされており、Opus 4.7では正常に機能しない（#49618）。hookはモデル非依存で動作するため、分類器の故障に関係なく防御が機能する。→ Opus 4.7 Survival Guide / Safety Scanner

⚠️ CVE-2026-21852（2026年4月公開）: プロジェクト内.claude/settings.json経由でAPIキー窃盗。対策: npx cc-safe-setup（ユーザーレベル設定で免疫）→ 詳細

📚 主張と実態の乖離の事例の整理と防衛の手順 (2026 年 5 月 22 日発売)

本記事の「hook を設定したのに動かない」は、利用者の意図 (防衛の発火) と実態 (hook の沈黙) の乖離の中核の系統。設定の場所、文体、マッチャの不一致、失敗の沈黙化の4件の原因の整理は、本書の第8章の防衛の手順の前提と整合。本書は同型の「設定したのに発火しない」系統の事例を、 settings.json、 CLAUDE.md、 /config、子の代理の前段、 memory の5つの場所に分散する形で整理。

5/22 発売の Claude Code Claim-Verify Handbook で、同型の主張と実態の乖離の事例を 130 件 (本文 15 件 + 付録 D 115 件) に整理した試し読み (無料、約 9,900 字、日本語) を公開済。 14 件の防衛の手順と 5 件の自動の点検の道具 (4 件は cc-safe-setup の枝で取り込み待機、 1 件は本書の付録の標準の道具、合計 165 件以上の試験が全件通過) も収録。

購入の検討の判断の助け (Should I buy the Claim-Verify Handbook?) の対話型の道具で、無料の hook の解説で十分の場合の判定の経路も整理しています。