[BUG] Subdirectory CLAUDE.md files not loaded on-demand when reading files via Read tool (VS Code extension, v2.1.39)

[GeoloeG-IsT]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

When using Claude Code via the VS Code extension (v2.1.39), subdirectory CLAUDE.md files are not loaded into context when Claude reads files in those directories using the Read tool.

According to the documentation, subdirectory CLAUDE.md files should be loaded on-demand when accessing files in that directory. In practice, only the root-level CLAUDE.md is loaded at session start, and no subdirectory CLAUDE.md files are ever injected — even after multiple Read tool calls into those directories.

What Should Happen?

When Claude reads a file like src/generation/orchestrator.ts, the src/generation/CLAUDE.md file (if it exists) should be loaded into the conversation context. If that CLAUDE.md contains @ imports (e.g., @AGENTS.md), those should also be resolved relative to that subdirectory.

Steps to Reproduce

1. Create a project with hierarchical CLAUDE.md files:

/project/
  CLAUDE.md              ← contains "@AGENTS.md"
  AGENTS.md              ← root-level docs
  src/
    generation/
      CLAUDE.md          ← contains "@AGENTS.md"  
      AGENTS.md          ← subdirectory-level docs
      orchestrator.ts

2. Open the project in VS Code with Claude Code extension
3. Start a conversation
4. Observe: root /project/CLAUDE.md and /project/AGENTS.md are loaded ✅
5. Ask Claude to read src/generation/orchestrator.ts (Claude uses the Read tool)
6. Ask Claude: "Which CLAUDE.md files are in your context?"

Expected: Both root CLAUDE.md and src/generation/CLAUDE.md (with resolved @AGENTS.md import)
Actual: Only root CLAUDE.md — the subdirectory one is never loaded

Concrete session evidence

In my session, Claude read files across 6 subdirectories (src/cli/, src/generation/, src/generation/writers/, src/orchestration/, src/update/, src/change-detection/) — all of which have CLAUDE.md files. None were loaded into context. The system prompt only ever contained:

Contents of /home/.../CLAUDE.md (project instructions, checked into the codebase):
Contents of /home/.../AGENTS.md (project instructions, checked into the codebase):

No subdirectory CLAUDE.md files appeared at any point during the conversation.

Additional context

This is a regression or continuation of the issue reported in:

• [BUG] CLAUDE.md files in subdirectories are not being automatically loaded #2571 — auto-closed due to inactivity, never actually fixed; confirmed still broken in VS Code extension
• [BUG] @ links in subdirectory CLAUDE.md files not resolved when opened from parent directory #18371 — @ links in subdirectory CLAUDE.md not resolved from parent directory (related but distinct)
• [Bug] Claude.md not loaded until first file read tool call in plan execution #18601 — CLAUDE.md not loaded until first file read in plan execution (related timing issue)

The combination of this bug + #18371 means that even if subdirectory loading were fixed, the @ imports inside those files might still not resolve. Both need to work for hierarchical project documentation to function as designed.

Error Messages/Logs

No error messages — the files are silently not loaded.

Environment Info

• Claude Code version: 2.1.39
• Platform: Linux (WSL2)
• IDE: VS Code extension
• OS: Linux 6.6.87.2-microsoft-standard-WSL2
• Model: Claude Opus 4.6

[github-actions]

Found 2 possible duplicate issues:

1. Feature request: Auto-load CLAUDE.md from subdirectories when working on files #18098
2. [Bug] Claude.md not loaded until first file read tool call in plan execution #18601

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[Gamrix]

I am getting the same issue. Asking Claude itself also confirms the same. :

/introspect Did you read playground/CLAUDE.md by this point?

No, I did not read playground/CLAUDE.md at any point in this conversation.

Here is everything relevant from my conversation context:

Root CLAUDE.md was auto-loaded in the system prompt:

Contents of /Users/johnclow/repos/sk-classifier-playground-1/CLAUDE.md (project instructions, checked into the codebase)

This is the project root CLAUDE.md, not playground/CLAUDE.md.

No Read tool call was ever made for playground/CLAUDE.md. My file reads in this conversation were limited to:

[snip]/playground/classifiers/optuna_mlp_binary.py (multiple times)
No Glob or Grep was done to discover nested CLAUDE.md files. I never searched for additional CLAUDE.md files in subdirectories..

/introspect  

Did you ever see text with 

uv run python -m [snip]

No, I never saw that command or anything resembling it in this conversation. There is no mention of [...]

I am getting this on:
2.1.45 (Claude Code)
Macos
VS Code extension

[GeoloeG-IsT]

@Gamrix as a workaround for my tool, I developed a hook that fixes that: https://github.com/GeoloeG-IsT/agents-reverse-engineer/blob/main/hooks/are-context-loader.js

[dsent]

Encountered the same behavior in VS Code extension 2.1.49. Claude CLI seems to work properly.
I'm on Windows.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.