read-once: 冗長なファイル読み込みを防ぐClaudeコードフック

開発者が「read-once」というPreToolUseフックを作成しました。このツールは、Claude Codeがセッション中に同じファイルを繰り返し読み込む傾向に対処し、不要なトークン消費を削減します。

問題と解決策

Claude Codeは、すでにコンテキストにあるファイルを再読み込みすることがよくあります。例えば、500行のファイルを開いて小さな編集をし、Claudeにファイル全体を再読み込みさせると、1回の読み込みで約2,000トークン以上かかります。典型的なセッションでは、同じファイルが5〜10回読み込まれる可能性があります。

read-onceフックは、Claudeが現在のセッションで読み込んだファイルを追跡します。Claudeが変更されていないファイルを再読み込みしようとすると、フックはそれをブロックし、「read-once: config.rs (~3,400トークン) はすでにコンテキストにあります (4分前に読み込み、変更なし)。セッション節約: ~12,000トークン」のようなメッセージを表示します。

仕組み

• 初回読み込み時: ファイルパス、変更時間、タイムスタンプを記録し、通常通り読み込みを許可します。
• 変更されていないファイルの再読み込み時: Claudeがすでに内容を持っているため、読み込みをブロックします。
• 変更されたファイルの再読み込み時: 完全な再読み込みを許可する代わりに、フックは差分を計算し、変更された部分のみを返します。Claudeはすでに古いバージョンをコンテキストに持っており、差分のみが必要です。3行が変更された500行のファイルの場合、約2,000トークンではなく約30トークンを使用し、ファイル反復で80〜95%を節約します。

機能と設定

このツールはTTL対応で、キャッシュエントリは20分後に期限切れになります（設定可能）。期限切れ後は、Claudeがコンテキストを圧縮して以前の内容を失った可能性があるため、再読み込みが許可されます。

設定は環境変数で行います:

• READ_ONCE_TTL=1200 - キャッシュが期限切れになるまでの秒数（デフォルト20分）
• READ_ONCE_DIFF=1 - 差分モードを有効化
• READ_ONCE_DIFF_MAX=40 - 完全再読み込みにフォールバックする前の最大差分行数
• READ_ONCE_DISABLED=1 - 完全に無効化

技術的詳細

このツール全体は、jqとdiff以外の依存関係がない約250行のbashで構成されています。MITライセンスで、.claude/settings.jsonフックに追加することでインストールされます。

開発者は、Claude Codeを自律ループで実行しており、トークンコストがすぐに増加するため、このツールを作成しました。差分モードだけで、セッションごとのトークン使用量が約30%削減されたと報告されています。