read-once: A Claude Code Hook That Prevents Redundant File Reads

A developer has created a PreToolUse hook called read-once that addresses Claude Code's tendency to repeatedly read the same files during a session, which consumes unnecessary tokens.

The Problem and Solution

Claude Code often re-reads files it already has in context. For example, opening a 500-line file, making a small edit, and having Claude read the entire file again costs approximately 2,000+ tokens per read. In typical sessions, the same files might be read 5-10 times.

The read-once hook tracks which files Claude has read in the current session. When Claude tries to re-read an unchanged file, the hook blocks it and displays a message like: "read-once: config.rs (~3,400 tokens) already in context (read 4m ago, unchanged). Session savings: ~12,000 tokens."

How It Works

• On first read: Records the file path, modification time, and timestamp, then allows the read normally.
• On re-read of unchanged file: Blocks the read since Claude already has the content.
• On re-read of changed file: Instead of allowing a full re-read, the hook computes the diff and returns only what changed. Claude already has the old version in context and just needs the delta. For a 500-line file where 3 lines changed, this uses ~30 tokens instead of ~2,000, saving 80-95% on file iterations.

Features and Configuration

The tool is TTL-aware with cache entries expiring after 20 minutes (configurable). After expiration, re-reads are allowed because Claude may have compacted the context and lost earlier content.

Configuration is done via environment variables:

• READ_ONCE_TTL=1200 - seconds before cache expires (default 20 min)
• READ_ONCE_DIFF=1 - enable diff mode
• READ_ONCE_DIFF_MAX=40 - max diff lines before falling back to full re-read
• READ_ONCE_DISABLED=1 - turn it off entirely

Technical Details

The entire tool is approximately 250 lines of bash with zero dependencies beyond jq and diff. It's MIT licensed and installs by adding itself to your .claude/settings.json hooks.

The developer built this tool because they run Claude Code in an autonomous loop where token costs add up quickly. The diff mode alone reportedly cut their per-session token usage by about 30%.