Claude Code の Hooks で保存前フォーマッターを自動実行する

Claude Code にコードを書いてもらった直後、prettier を手動で走らせる手間が地味に積み重なります。Claude が生成するコードはフォーマットルールをほぼ守りますが、インデントや末尾セミコロンがわずかにズレることがあります。

PostToolUse フックを使えば、ファイルへの書き込みや編集が完了するたびにフォーマッターが自動実行されます。この記事では設定の全文と、実際に詰まった落とし穴を共有します。

プロジェクト内に prettier がインストールされている場合はそちらが優先されます。グローバルインストールがなくても npx prettier で動作します。

Claude Code の Hooks は、セッションのライフサイクル上の特定ポイントでシェルコマンドを自動実行する機能です（公式ドキュメント）。フック型は command / http / prompt / agent の 4 種類があります。

フォーマット自動化に使うイベントは PostToolUse。ツールが正常完了した後に発火します（出典）。Write や Edit ツールへのマッチャーを設定しておくと、Claude がファイルを書き出すたびにスクリプトが動きます。

フックスクリプトは stdin でイベント情報を JSON として受け取ります。Write ツールの場合、tool_input.file_path に書き込まれたファイルのパスが格納されています（出典）。この値を jq で取り出してフォーマッターに渡すのが基本の流れです。

.claude/settings.json（プロジェクト内）に以下を追記します。

$CLAUDE_PROJECT_DIR はプロジェクトルートを指す環境変数です。パスにスペースが含まれるケースに備え、ダブルクォートで囲んでいます（出典）。"Write|Edit" は | 区切りで複数ツールを指定する書き方です（出典）。

.claude/hooks/format.sh を次の内容で作成します。

jq -r '.tool_input.file_path' で stdin の JSON からファイルパスを取り出せることは検証済みです。npx prettier はグローバルインストールがない環境でも動作することを確認しています（Prettier 3.8.3）。

実行権限を付与します。

Prettier を Biome に置き換える場合は format --write に差し替えます。

Claude Code でプロジェクトを開き、フォーマットが崩れた状態でファイルを書かせてみます。「test.ts に const x=1 と書いて」と指示し、書き込まれたファイルが const x = 1; になっていれば成功です。

なお、$CLAUDE_PROJECT_DIR が実際のプロジェクトルートを正しく指すかどうか、および npx prettier が PostToolUse から問題なく呼び出せるかは、お使いの環境での手元確認が必要です。詳しい確認手順は verification/manual-steps.md を参照してください。

Claude Code は exit 0 のとき stdout を JSON としてパースしようとします。スクリプト内に echo でデバッグ出力を入れると、JSON でない文字列が stdout に流れてパースエラーになります（検証済み）。デバッグ出力は必ず >&2（stderr）に向けてください。

~/.bashrc や ~/.zshrc が起動時に何かを echo している場合も同様にパースが壊れます。シェルプロファイルの出力は抑制するか、スクリプト内で bash --noprofile --norc を使って起動してください。

フックスクリプトが実行されるときの PATH は、通常のターミナルセッションとは異なることがあります。prettier が直接解決できない場合は npx prettier を使います。npx 自体も解決できない場合は絶対パスで指定します。

PostToolUse フックで exit 2 を返しても、ツールの実行はブロックできません。ツールはすでに完了しているためです（出典）。exit 2 を返した場合は stderr の内容が Claude へのエラーコンテキストとして渡され、Claude が追加処理を試みることがあります。フォーマッタースクリプトでは exit 0 を返すだけで十分です。