Claude Code has a hook system that most people don’t use. It lets you intercept tool calls (Read, Write, Bash, Edit) before or after they execute. You can block calls, modify behavior, add logging, enforce rules. It runs your shell script, reads the exit code and stdout, and acts on it.

I built read-once, a hook that prevents Claude from re-reading files it already has in context. This post covers what I learned building it: the patterns that work, the gotchas, and how to build your own.

The hook contract

A hook is a shell command that Claude Code runs at specific lifecycle points. The two main ones:

• PreToolUse: runs before a tool executes. Can allow, block, or modify the call.
• PostToolUse: runs after a tool executes. Can log, validate, or react.

Your hook receives JSON on stdin describing the tool call:

{
  "tool_name": "Read",
  "tool_input": {
    "file_path": "/Users/you/project/src/main.rs"
  },
  "session_id": "abc123..."
}

Your hook’s job: read that JSON, decide what to do, and respond.

Response protocol

To allow the call (or if your hook doesn’t apply), just exit 0 with no output:

exit 0

To block the call, output a JSON response with permissionDecision: "deny":

cat <<EOF
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Reason shown to Claude"
  }
}
EOF
exit 0

The permissionDecisionReason is what Claude actually sees. Make it informative. Claude uses it to decide what to do next.

Setting up hooks in settings.json

Hooks live in ~/.claude/settings.json (global) or .claude/settings.json (project). The structure:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/my-hook/hook.sh"
          }
        ]
      }
    ]
  }
}

The matcher filters which tool triggers the hook. Set it to a specific tool name ("Read", "Bash", "Edit") or omit it to match everything.

A minimal hook: logging all file reads

Start simple. This hook logs every file Claude reads:

#!/bin/bash
set -euo pipefail

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')

if [ "$TOOL" != "Read" ]; then
  exit 0
fi

FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
echo "$(date +%s) READ $FILE" >> ~/.claude/read-log.txt

exit 0

No blocking, no output to stdout. Just a side effect (appending to a log). Claude never knows this hook exists.

Pattern: session-scoped state

Hooks are stateless by default. Each invocation is a fresh process. But the session_id field lets you build session-scoped state.

The pattern I use in read-once:

SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty')
SESSION_HASH=$(echo -n "$SESSION_ID" | shasum -a 256 | cut -c1-16)
CACHE_FILE="${HOME}/.claude/my-hook/session-${SESSION_HASH}.jsonl"

Each session gets its own JSONL cache file. Append entries as you go:

echo "{\"path\":\"${FILE}\",\"ts\":$(date +%s)}" >> "$CACHE_FILE"

Then grep the cache on future invocations to check if you’ve seen this file before.

Clean up old sessions periodically:

find "$CACHE_DIR" -name 'session-*.jsonl' -mtime +1 -delete 2>/dev/null || true

Pattern: the deny reason as instruction

When you block a tool call, the permissionDecisionReason is your one chance to tell Claude what happened and what to do instead. Make it count.

Bad:

"permissionDecisionReason": "Blocked."

Good:

"permissionDecisionReason": "read-once: config.yml (~1,200 tokens) already in context (read 4m ago, unchanged). Re-read allowed after 20m."

Claude reads this and adjusts its behavior. In read-once’s case, Claude stops trying to re-read the file and uses the content it already has. The token estimate tells Claude how much it saved, which reinforces the behavior.

Gotcha: partial reads

Claude sometimes reads files with offset and limit parameters (browsing a large file section by section). If you’re caching file reads, don’t cache partial reads. Each chunk is different content:

OFFSET=$(echo "$INPUT" | jq -r '.tool_input.offset // empty')
LIMIT=$(echo "$INPUT" | jq -r '.tool_input.limit // empty')

if [ -n "$OFFSET" ] || [ -n "$LIMIT" ]; then
  exit 0  # Don't cache partial reads
fi

Gotcha: context compaction

Claude Code compacts its context window during long sessions, dropping older content. A file read 30 minutes ago might no longer be in Claude’s working memory. If your hook blocks re-reads, you need a TTL:

TTL=1200  # 20 minutes
ENTRY_AGE=$(( $(date +%s) - CACHED_TS ))

if [ "$ENTRY_AGE" -ge "$TTL" ]; then
  # Allow the re-read, content may have been compacted
  exit 0
fi

There’s no API to detect compaction events, so a time-based heuristic is the best you can do. 20 minutes works well in practice.

Gotcha: performance

Your hook runs synchronously before every matching tool call. If it takes 500ms, every file read takes 500ms longer. Keep it fast:

• Use grep -F (fixed string) instead of regex when possible
• Don’t call external APIs
• Write caches to local files, not databases
• jq is fast enough for parsing the input JSON. Don’t overthink it

Hook ideas

Beyond file read deduplication, hooks can do a lot:

• Auto-approve patterns: Allow known-safe commands without prompting
• Cost tracking: Count tokens read/written per session
• Security gates: Block writes to production config files
• Style enforcement: Run a linter on PostToolUse for Write/Edit
• Audit trail: Log every tool call with timestamps for compliance

Full example: blocking writes to .env

A simple but useful hook. Prevent Claude from accidentally overwriting .env files:

#!/bin/bash
set -euo pipefail

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty')

case "$TOOL" in
  Write|Edit) ;;
  *) exit 0 ;;
esac

FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

if [[ "$FILE" == *".env"* ]]; then
  cat <<EOF
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Protected: .env files cannot be modified by hooks policy. Ask the user to make this change manually."
  }
}
EOF
fi

exit 0

Add it to settings.json with "matcher": "Write" (and a second entry for "Edit"), and .env files are safe.

Where hooks fit

Hooks are one layer in the Claude Code extension stack:

• Hooks intercept tool calls (bash scripts, low-level)
• Skills add knowledge and workflow patterns (SKILL.md files)
• MCP servers add entirely new tools (JSON-RPC protocol)

Hooks are the simplest to build and the most immediate in effect. No SDK, no server process, no protocol. Just a bash script and a JSON contract.

Resources

• read-once: the token-saving hook I built, MIT licensed
• Claude Code hooks documentation in ~/.claude/settings.json

The hook system is underused. If you’ve built something interesting with it, I’d like to hear about it.