概要

cc-read-limit-hook は Claude Code の PreToolUse フックとして利用する小さな Python スクリプトで、ファイル読み取りリクエストに対して制限とガイドを適用します。目的は「不要に大きなファイルを丸ごと読み込ませない」ことで、モデルのコンテキスト使用量を節約し、処理コストや応答の遅延を抑えることです。具体的には読み取り行数・バイト数の閾値を設け、閾値を超える場合は offset と limit の指定を必須にしたり、offset のみ指定された場合は自動で limit を追加するなどの挙動を取ります。さらに試行ログを残して読み取りパターンの分析を可能にします。

リポジトリの統計情報

スター数: 20
フォーク数: 1
ウォッチャー数: 20
コミット数: 2
ファイル数: 2
メインの言語: Python

主な特徴

大きなファイルの全読み取りをブロック（>1000行または >50KB の場合は offset+limit 必須）
単一読み取りの上限を設定（最大500行 / 20KB）
offset のみ指定された場合に自動で適切な limit を追加
読み取り試行の統計ログを記録し、解析に利用可能

技術的なポイント

cc-read-limit-hook は比較的シンプルな設計で、主に「入力検査」「リクエスト修正」「ログ出力」の3つの責務を持ちます。入力検査では、読み取り対象ファイルの行数とサイズ（バイト数）を確認し、事前に定められた閾値と照合します。閾値の条件分岐により、問題がなければそのまま読み取りを許可し、閾値を超える場合は offset と limit の併用を要求します。実装はファイルのメタ情報（os.path.getsize のような手段や、必要に応じてファイルを走査して行数をカウントする）を参照する想定です。

リクエスト修正機能は「offset のみ与えられているが limit がない」場合に限って自動的に limit を追加する仕組みで、モデルやツールからの曖昧な要求を安全に補完する役割を果たします。これにより、開発者が細かいパラメータを毎回指定し忘れても過剰な読み込みを防ぐことができます。一方で、完全にブロックするケースではユーザー（もしくはモデル）へ適切なエラーメッセージやガイドを返して再試行を促します。

ログ周りでは、読み取りリクエストのメタ（ファイル名、要求された offset/limit、禁止理由や自動補完の有無、タイムスタンプなど）を集約して保存し、後でアクセスパターンやポリシーのチューニングに使えるようにします。ログはローカルファイルや標準出力、あるいはアプリケーションのロギングシステムに吐く構成が考えられます。

設計上の注意点としては、フックはあくまで「リクエスト前のガード」であり、実際のファイル読み取りを行うプロセスやツール側がこのフックを無視できないことが前提になります。また行数の算出やバイト数の測定は I/O 負荷を増やす可能性があるため、メタ情報キャッシュや高速な推定手法（例えば拡張子ごとの平均行長を使った推定）を導入する余地があります。拡張案としては閾値を設定ファイル化する、プロジェクト単位で例外ルールを作る、読み取り要求に対するユーザー承認ワークフローを組み込む等が挙げられます。

プロジェクトの構成

主要なファイルとディレクトリ：

README.md: file
read-guard.py: file

read-guard.py はフック本体で、ファイル読み取りリクエストを受け取り制限ロジックを適用する処理を含みます。README.md には機能の説明（英中併記）と簡単な使用例、制限値（1000行/50KB/500行/20KB など）の一覧が記載されています。

まとめ

Claude Code と組み合わせた簡易的な読み取り制御フックで、コンテキスト消費の抑止に有用です。

リポジトリ情報：

名前: cc-read-limit-hook
説明: A hook that limit and guide how claude code read files.
スター数: 20
言語: Python
URL: https://github.com/Cedriccmh/cc-read-limit-hook
オーナー: Cedriccmh
アバター: https://avatars.githubusercontent.com/u/114600267?v=4

READMEの抜粋：

cc-read-limit-hook

A Claude Code PreToolUse hook that enforces file read limits to optimize context usage.

一个 Claude Code PreToolUse 钩子，用于限制文件读取范围以优化上下文使用。

Features / 功能

Block large file reads - Files >1000 lines or >50KB require offset + limit parameters
Limit single reads - Max 500 lines / 20KB per read operation
Auto-add limit - Automatically adds limit when only offset is specified
Statistics logging - Logs read attempts for analysis

阻止大文件读…

cc-read-limit-hook — Claude Code 用ファイル読み取り制限フック