Custom PostToolUse Hook for On-Demand CLAUDE.md Loading Outside Project Tree

CLAUDE.md Loading Behavior in Claude Code

The source details how Claude Code handles CLAUDE.md files under different conditions:

• Hierarchical loading: When starting a session in a subdirectory, both the local CLAUDE.md and parent directory CLAUDE.md files are loaded. Example: Session in root/a/ loads both root/a/CLAUDE.md and root/CLAUDE.md.
• On-demand child directory loading: Child directories of the current session's root directory load their CLAUDE.md files when Claude accesses files in those directories. Example: Session in root/ loads root/CLAUDE.md initially, then loads root/a/CLAUDE.md when Claude reads a file in root/a/.
• Additional directory access via flags: Using --add-dir with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 allows access to CLAUDE.md files in directories outside the project tree, but these load at session start rather than on-demand.

The Problem: External Directory CLAUDE.md Files Not Loading On-Demand

The author notes that when working in one project and instructing Claude to read files from directories outside the session's directory tree, any CLAUDE.md files in those external directories won't load automatically. This creates issues for progressive disclosure of context and requires manual intervention each time.

Solution: Custom PostToolUse Hook

The solution involves creating a PostToolUse hook that:

• Checks if Claude is operating outside the project tree on each tool call
• Walks up from that directory looking for CLAUDE.md files
• If found, exits with code 2 to feed instructions back to Claude telling it to read them
• Tracks which files have already been surfaced in a session-scoped temp file to avoid repeated instructions

A SessionStop hook cleans up the temp file used for tracking. The author provides a script called check_claude_md.py (source linked in original post) that implements this PostToolUse hook functionality.

Practical Implementation

The approach addresses the specific limitation where external directory CLAUDE.md files only load at session start when using the --add-dir flag with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. By intercepting tool calls and checking for operations outside the project tree, the hook enables on-demand loading similar to how child directories work within the project tree.

This type of custom hook is useful for developers who frequently work across multiple projects or need to reference shared context files from external directories without manually instructing Claude to read CLAUDE.md files each time.