Claude Code hooksのイベントを試してみた
はじめに
お疲れ様です。あきとです。
今回はClaude Code hooksのイベントについて調べる機会がありましたので、実際に試してみた内容を共有したいと思います。
背景・動機
下記のClaude Code hooksについて解説している記事を見ながら作業していたところ、イベントの種類が増えていることに気づきました。CHANGELOGを確認したところ、新たに4つのイベント（UserPromptSubmit、PreCompact、SessionStart、SessionEnd）が追加されていることがわかりましたので、これらのイベントについて何ができるか調べてみました。
hooksの基本的な使い方と既存のイベントについては以下の記事を参照してください。
Claude Code hooksのイベント一覧
現在利用可能なhooksイベントは以下の通りです：
| イベント名 | 実行タイミング | 主な用途 |
|---|---|---|
| PreToolUse | Claude がツールを実行する直前 | コマンド検証、入力修正、権限チェックなど |
| PostToolUse | ツール実行直後 | 結果検証、ロギング、後処理 |
| Notification | 通知時（例: ユーザー確認待ち） | 通知の監視や自動反応 |
| Stop | メインエージェントの応答終了時 | 終了処理や保存 |
| SubagentStop | サブエージェント終了時 | タスクレポートやサブ処理後処理 |
| ★ UserPromptSubmit | ユーザーがプロンプト送信時 | 入力検証、禁止ワードチェック |
| ★ PreCompact | コンテキスト圧縮前 | コンパクト操作に応じた処理 |
| ★ SessionStart | 新規または再開セッション開始時 | 環境初期化、依存関係のセットアップ |
| ★ SessionEnd | セッション終了時 | クリーンアップ、ログ保存 |
追加されたイベントと用途は以下の4つです（以下、公式ドキュメントより翻訳）：
-
UserPromptSubmit: ユーザーがプロンプトを送信したときに、Claude が処理を始める前に実行される。
これにより、プロンプトや会話の内容に基づいて追加のコンテキストを付与したり、プロンプトを検証したり、特定の種類のプロンプトをブロックしたりできる。 -
PreCompact: Claude Code がコンパクト（圧縮）処理を実行する直前に実行される。
マッチャー（発火条件）は以下の通り：- manual：ユーザーが /compact コマンドを実行したときに呼び出される
- auto：コンテキストウィンドウがいっぱいになったために、自動圧縮が行われるときに呼び出される
-
SessionStart: Claude Code が新しいセッションを開始するか、既存のセッションを再開するときに実行される（現在のところ、再開操作も内部的には新しいセッションの開始として扱われる）。
このフックは、開発コンテキストの読み込み（例：既存の課題や最近のコード変更の取得）、依存関係のインストール、環境変数の設定などに利用できる。
マッチャー（発火条件）：- startup：起動時に呼び出される
- resume：--resume、--continue、または /resume コマンドで再開されたときに呼び出される
- clear：/clear コマンド実行時に呼び出される
- compact：自動または手動のコンパクト（圧縮）処理時に呼び出される
-
SessionEnd: Claude Code のセッションが終了したときに実行される。
このフックは、クリーンアップ処理・セッション統計の記録・セッション状態の保存などに利用できる。
reason フィールド（終了理由）は以下のいずれかになる：- clear：/clear コマンドでセッションがクリアされた
- logout：ユーザーがログアウトした
- prompt_input_exit：プロンプト入力画面が表示されている状態でユーザーが終了した
- other：その他の終了理由
使ってみた
実際にイベントを使った処理を作ってみました。
1: UserPromptSubmitでultrathinkを自動追加
ユーザーがプロンプトを送信するたびに、自動的に「ultrathink」を追加するhooksを実装してみました。
まず、.claude/settings.jsonに以下の設定を追加します：
"hooks": {
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "./append-ultrathink.sh"
}
]
}
]
}
次に、スクリプトを作成します：
#!/bin/bash
# append-ultrathink.sh
# 標準入力をすべて読み込む
input=$(cat)
# "ultrathink" が既に含まれているか確認（大文字小文字を無視）
if echo "$input" | grep -iq "ultrathink"; then
# すでに含まれていれば、そのまま出力
echo "$input"
else
# 含まれていなければ、改行付きで追加
echo -e "${input}\n\nultrathink"
fi
常にultrathinkを入れるなら環境変数でトークン数指定した方が簡単なので、実用性を考えると日本語で短めのキーワードを指定してultrathinkに置き換えるような実装の方が扱いやすいなと、書きながら思いました。
2: PreCompactで自動圧縮を通知
Claude Codeが自動的にコンテキストを圧縮する際に、音で通知するhooksを実装しました。これにより、気づかないうちにコンテキストが圧縮されることを防ぎます。
"PreCompact": [
{
"matcher": "auto",
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Glass.aiff"
}
]
}
]
この設定により、自動圧縮が実行される前にmacOSのシステムサウンドが再生されます。
自動圧縮に気づかないことがあるため、今回は音で通知する実装にしましたが、通知方法は用途に応じて選択すると良いでしょう。
3: SessionStart/SessionEndでログ記録
Claude Codeのセッション開始時と終了時にログを記録するhooksを実装しました。これにより、作業履歴を自動的に追跡できます。
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "./session_log.sh"
}
]
}
],
"SessionEnd": [
{
"hooks": [
{
"type": "command",
"command": "./session_log.sh"
}
]
}
]
}
ログ記録用のスクリプト：
#!/bin/bash
# ./session_log.sh
log_dir="./.claude/logs"
mkdir -p "$log_dir"
timestamp=$(date +"%Y%m%d-%H%M%S")
input=$(cat)
# 全体をまとめた最終ログ保存（JSON Lines形式で追記）
echo "[${timestamp}] $input" >> "$log_dir/session_log.jsonl"
# Claudeには内容をそのまま返す
echo "$input"
このスクリプトは以下のことを行います：
.claude/logsディレクトリを作成（存在しない場合）- タイムスタンプ付きでセッション情報をログファイルに追記
- 処理した内容をそのままClaude Codeに返す
個人での利用ではあまり活用する場面がないかもしれませんが、最も標準的な使い方だと考えたため紹介しました。今回は発火条件をすべて設定していますが、実際に使用する際は必要なものに絞ることをお勧めします。
まとめ
今回はClaude Code hooksに追加されていたイベント（UserPromptSubmit、PreCompact、SessionStart、SessionEnd）について実際に試してみました。これらのイベントを活用することで、外部のアプリなどと連携したClaude Codeのカスタマイズができ、確実にアクションを起こすことができます。
hooksを適切に設定することで、Claude Codeをより快適に使用できるようになります。本ブログが誰かの参考になれば幸いです。
参考資料
- Claude Code hooksについて解説してみる | DevelopersIO - hooksの基本的な使い方
- Claude Code 公式ドキュメント - Claude Codeの公式技術仕様
- claude-code/CHANGELOG.md at main · anthropics/claude-code · GitHub - Claude Codeのアップデート情報
アノテーション株式会社について
アノテーション株式会社は、クラスメソッド社のグループ企業として「オペレーション・エクセレンス」を担える企業を目指してチャレンジを続けています。「らしく働く、らしく生きる」のスローガンを掲げ、様々な背景をもつ多様なメンバーが自由度の高い働き方を通してお客様へサービスを提供し続けてきました。現在当社では一緒に会社を盛り上げていただけるメンバーを募集中です。少しでもご興味あれば、アノテーション株式会社WEBサイトをご覧ください。
