Feature Request: Auto-load CLAUDE.md files from submodules
## Description
When working with repositories that contain submodules, Claude Code should automatically load and consider CLAUDE.md files from both the
main repository and its submodules when providing assistance.
## Current Behavior
Currently, Claude Code only loads the CLAUDE.md file from the current working directory at startup. When a repository contains submodules
(like frameworks or libraries) with their own CLAUDE.md files, these aren't loaded automatically, requiring manual loading requests.
## Proposed Behavior
Claude Code should:
- Detect git submodules within the repository
- Automatically load CLAUDE.md files from these submodules at startup
- Intelligently merge or prioritize information based on the files being worked on
- Consider module-specific documentation when working with files from that submodule
## Additional Configuration Capability
Implement a configuration file (e.g., CLAUDE.config.json or .clauderc) at the repository root that would allow:
- Explicitly specifying additional paths to search for CLAUDE.md files
- Excluding certain submodules or directories from auto-loading
- Setting priority/precedence for conflicting instructions
- Controlling how documentation is merged or segmented
Example configuration:
``json``
{
"documentation": {
"include": [
"./core-framework/CLAUDE.md",
"./docs/conventions.md"
],
"exclude": [
"./third-party/**/CLAUDE.md"
],
"priority": [
"./CLAUDE.md",
"./core-framework/CLAUDE.md"
]
}
}
Use Cases
- Working with modular applications built on frameworks
- Repositories with separate but related components, each with specialized documentation
- Projects that integrate multiple libraries, each with specific usage guidelines
Benefits
- More complete contextual understanding of the codebase
- Faster assistance with submodule-specific code
- Reduced need for repetitive loading of documentation
- Better adherence to module-specific conventions and patterns
Implementation Suggestions
- Add a configuration option in claude.json to control this behavior
- Provide a way to specify priority when multiple CLAUDE.md files might conflict
- Consider a hierarchical approach where more specific documentation overrides general documentation
Example
In a typical web application structure:
- Main app code in /src/ with /CLAUDE.md containing app-specific guidelines
- Framework code in /core-framework/ with /core-framework/CLAUDE.md containing framework-specific documentation
Currently, when working with framework files, Claude doesn't automatically know about the framework-specific patterns documented in the
submodule's CLAUDE.md.
7 Comments
This is supported today! Claude should load in CLAUDE.md's from subfolders on demand, when you work on code in those folders. Is that not working for you?
I've been playing around with this and sometimes it's difficult to tell if Claude is loading these files or not. Sometimes it will use a tool to read the file, in which case it's obvious, but other times, I don't see any command that reads the file, but it feels like it has the context anyways.
Maybe adding some clarity in the tool when Claude automatically reads these files (without tool use?) would help?
Also, it doesn't seem like it consistently loads the CLAUDE.md file from the directory you run
> claudein. I have a set of guidelines in that file that sometimes Claude will not follow, but after asking it to check the file, he will. Is this file automatically loaded into it's context every time? Or is it conditional?PS - Claude Code is an absolutely next level tool. Probably the most impactful tool I've used for actual day to day workflows for software engineering. Huge props to the Anthropic team. It really shows that you guys are dogfooding this thing!
Ah, I assumed it did. Can someone from Anthropic tell us if Claude always reads the launch folder's CLAUDE.md file when it starts? Claude seems to think so:
PS - I agree that this tool is amazing!
Claude always reads the CLAUDE.md from the folder you launch it in, automatically. If it's not following instructions, it would be helpful if you could file a
/bugso we can dig into the transcript.When Claude pulls in CLAUDE.md's from child directories, it will always show up as a file read. If you don't see that file read, the CLAUDE.md is not getting pulled in. Similarly, it would help if you could run
/bugif you don't see this happening.Thanks for the kind words and please keep the feedback coming!
Thanks for the response but I'm confused as to why this was closed. The feature request was for Claude to find and read all CLAUDE.md files in the project, not just the top one. Was this request closed because Claude already reads all those files on startup or because the request was rejected?
For me, Claude does not read CLAUDE.md files in subprojects/subfolders. I'm tinkering with adding instructions in the root CLAUDE.md to get it to read the others on startup, but so far that's not working.
UPDATE: Adding the following to the main CLAUDE.md files seems to work for me. I'm glad it works but FWIW I still think this should be the default behavior (or part of the default main CLAUDE.md template) as I suspect this is the way most users will assume it works and will be frustrated to discover otherwise.
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.