Feature: CLAUDE.md inheritance should traverse into git submodules
Problem
When working in a monorepo that uses git submodules, CLAUDE.md files are not inherited between the parent repo and its submodules — despite them being physically nested directories on disk.
Current behavior
Claude Code loads CLAUDE.md files hierarchically through nested directories:
project/
├── .claude/CLAUDE.md ← loaded
├── packages/
│ └── api/
│ └── .claude/CLAUDE.md ← loaded (inherits from parent)
However, when the nested directories are git submodules, the inheritance chain breaks:
project/
├── .claude/CLAUDE.md ← loaded when working from parent
├── submodule-a/ ← has its own .git file
│ └── .claude/CLAUDE.md ← loaded when working from submodule-a, but does NOT inherit parent
- From the parent repo: submodule CLAUDE.md files are not loaded
- From inside a submodule: parent repo CLAUDE.md is not loaded
Why this matters
In a multi-project workspace with submodules (e.g., a SaaS ecosystem with separate repos for API server, frontend dashboard, bot core, landing page, store, etc.), the parent repo's CLAUDE.md typically contains ecosystem-wide context — how services communicate, architecture overview, shared conventions. This context is critical regardless of which submodule you're working in.
Currently, users must either:
- Duplicate context across all submodule CLAUDE.md files (violates DRY)
- Always work from the parent repo (limits workflow flexibility)
- Put ecosystem context in the global
~/.claude/CLAUDE.md(pollutes global config with project-specific info)
Proposed solution
Treat git submodules as nested directories for the purpose of CLAUDE.md loading. Since submodules are physically nested folders on disk, the inheritance chain should work the same way:
- When working from a submodule: load CLAUDE.md files from the submodule up through parent directories, even if a parent directory is a different git repo
- When working from the parent: optionally load CLAUDE.md files from submodule directories when navigating into them during a task
This would be consistent with how the filesystem actually looks and would make monorepo + submodule workflows seamless.
Environment
- Windows 11 / Git submodules
- Workspace with 8+ submodules across different tech stacks (Lua, Next.js, Node.js)
This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗