Feature: CLAUDE.md inheritance should traverse into git submodules

Resolved 💬 4 comments Opened Apr 7, 2026 by Kizuno18 Closed May 25, 2026

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:

  1. 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
  2. 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)

View original on GitHub ↗

This issue has 4 comments on GitHub. Read the full discussion on GitHub ↗