Claude Code hooks設定

hooksとは

特定のタイミングで自動実行されるスクリプト。Claude Codeの動作をカスタマイズできる。

設定ファイル: ~/.claude/settings.json

hookの種類

タイミング	説明	用途例
`SessionStart`	セッション開始時	環境確認・INDEX更新
`PreToolUse`	ツール実行前	危険コマンドのブロック
`PostToolUse`	ツール実行後	ログ記録・自動整形
`PostToolUseFailure`	ツール失敗時	エラー記録
`Stop`	セッション終了時	ログ保存・ハンドオフ生成
`Notification`	通知時	Discord通知等

基本構造

"hooks": {
  "SessionStart": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "/path/to/script.sh",
          "timeout": 5000
        }
      ]
    }
  ]
}

matcher: ツール名で絞り込み。"" = 全ツール、"Bash" = Bashのみ、"Edit|Write" = 複数指定

必ず hooks 配列の中に type と command を入れること。直接 command を書くとエラーになる。

実例: セッション開始時に挨拶

"SessionStart": [
  {
    "matcher": "",
    "hooks": [
      {
        "type": "command",
        "command": "echo 'セッション開始しました'",
        "timeout": 3000
      }
    ]
  }
]

実例: 危険コマンドをブロック

"PreToolUse": [
  {
    "matcher": "Bash",
    "hooks": [
      {
        "type": "command",
        "command": "/path/to/guard-destructive.sh",
        "timeout": 3000
      }
    ]
  }
]

スクリプトが exit 1 を返すとツール実行がブロックされる

実例: 編集後に自動処理

"PostToolUse": [
  {
    "matcher": "Edit|Write",
    "hooks": [
      {
        "type": "command",
        "command": "echo '$TOOL_INPUT' | python3 check.py",
        "timeout": 5000
      }
    ]
  }
]

$TOOL_INPUT でツールの入力内容（JSON）にアクセス可能

トラブルシューティング

症状	原因	対処
hooksエラーで起動失敗	JSON構文エラー	`hooks` 配列構造を確認
hookが実行されない	matcherが合ってない	ツール名とmatcherを確認
タイムアウトする	スクリプトが重い	timeout値を増やす or スクリプトを軽くする

← ガイド一覧に戻る