[FEATURE] Add git submodule path support for LS, Grep, and Glob tools
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] This is a single feature request (not multiple features)
Problem Statement
Currently, when Claude Code uses tools like LS, Grep, and Glob, it ignores git submodules within the project. I discovered this issue while using the CC SDK - the tool output excludes paths from git submodules entirely. Since submodules often contain critical dependencies and related code, having access to them is essential for Claude Code to properly understand and navigate the full project structure.
Proposed Solution
Enable Claude Code tools (LS, Grep, Glob, etc.) to traverse and include git submodules in their operations. This would allow CC to access and analyze code within submodules, providing a more comprehensive understanding of the entire project ecosystem.
Alternative Solutions
_No response_
Priority
High - Significant impact on productivity
Feature Category
File operations
Use Case Example
- Monorepo with shared libraries: Many projects use git submodules to manage shared code libraries. For instance, a project might have a shared-utils submodule that contains common utilities used across multiple services. Without submodule access, Claude Code cannot analyze dependencies, understand function implementations, or refactor code that relies on these shared components.
- Third-party dependencies as submodules: Some projects vendor their dependencies as git submodules for better version control and customization. When Claude Code cannot access these submodules, it's unable to:
- Trace function calls into vendored libraries
- Understand the full context of API usage
- Debug issues that span across the main project and its dependencies
- Cross-project configuration and schemas: Projects often maintain shared configuration schemas, protobuf definitions, or API contracts in submodules. Without access to these, Claude Code cannot properly validate configurations or understand the data structures being used.
- Microservices architecture: In a microservices setup where each service is a submodule, Claude Code currently cannot navigate between services, making it difficult to understand inter-service communication, shared interfaces, or perform project-wide refactoring.
Example scenario:
my-project/
├── src/
│ └── main.py # imports from libs/shared-auth
├── libs/
│ ├── shared-auth/ # <-- git submodule (currently invisible to CC)
│ └── shared-db/ # <-- git submodule (currently invisible to CC)
└── services/
└── api-gateway/ # <-- git submodule (currently invisible to CC)In this structure, Claude Code cannot currently analyze any code within the submodules, significantly limiting its understanding of the project.
Additional Context
_No response_
6 Comments
This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.
I am experiencing same issue.
Claude is able to read submodules in windows, but when it tries to edit a file constantly gets:
Error: File has been unexpectedly modified. Read it again before attempting to write it.For what it's worth, I have not had any problems reading or writing across git submodules in Claude Code 2.0.76. Including a full excerpt from Claude Code (with redactions) below.
<details>
<summary>Excerpt</summary>
```
"Search",
"Read",
"Bash(ls:*)",
"Bash(find:*)",
"Bash(grep:*)",
"Bash(cat:*)"
⏺ I'll help you explore the git submodules in this repository. Let me first identify what submodules exist and then run the appropriate commands across them.
⏺ Bash(git submodule status)
⎿ c3fe3ffe1d23493edd2343ac76257e466cd98d96 projects/PROJECTB/PROJECT_web (heads/main)
+e068d476d692c8a98c18af8a8b2e765938127b89 projects/PROJECTA/PROJECTA_backend (heads/MVP-8-tracking-endpoint)
0a1547ac849fcdc955f6c5e3a453e6002dddb2fd projects/PROJECTA/PROJECTA_unity (heads/start-screan)
⏺ Read(.gitmodules)
⎿ Read 17 lines
⏺ Now let me explore each of the 4 submodules by listing their contents:
⏺ Bash(ls -la projects/PROJECTA/PROJECTA_unity)
⎿ drwxr-xr-x - ianwalker-sperber 29 Nov 04:43 .claude
.rw-r--r-- 63 ianwalker-sperber 4 Nov 05:34 .git
drwxr-xr-x - ianwalker-sperber 4 Nov 05:34 .github
… +22 lines (ctrl+o to expand)
⏺ Bash(ls -la projects/PROJECTA/PROJECTA_backend)
⎿ drwxr-xr-x - ianwalker-sperber 12 Dec 13:29 .aws
drwxr-xr-x - ianwalker-sperber 11 Dec 09:58 .claude
.rw-r--r-- 109 ianwalker-sperber 12 Dec 13:09 .env
… +16 lines (ctrl+o to expand)
⏺ Bash(ls -la projects/PROJECT/PROJECTB_web)
⎿ drwxr-xr-x - ianwalker-sperber 19 Dec 04:56 .aws
.rw-r--r-- 67 ianwalker-sperber 19 Dec 04:56 .git
.rw-r--r-- 480 ianwalker-sperber 19 Dec 04:56 .gitignore
… +10 lines (ctrl+o to expand)
⏺ Bash(ls -la projects/PROJECT/PROJECTB_api)
⎿ Error: Exit code 2
"projects/PROJECT/PROJECTB_api": No such file or directory (os error 2)
⏺ I found 3 active submodules (the 4th, PROJECTB_api, is not yet initialized). Let me read their README files and explore their .thoughts directories:
⏺ Read(projects/PROJECTA/PROJECTA_unity/README.md)
⎿ Read 47 lines
⏺ Read(projects/PROJECTA/PROJECTA_backend/README.md)
⎿ Read 13 lines
⏺ Read(projects/PROJECTB/PROJECT_web/README.md)
⎿ Read 37 lines
⏺ Bash(find projects/PROJECTA/PROJECTA_unity/.thoughts -type f -name "*.md" 2>/dev/null | head -20)
⎿ projects/PROJECTA/PROJECTA_unity/.thoughts/MVP-7 Approximation Answers/MVP-7 PRD.md
projects/PROJECTA/PROJECTA_unity/.thoughts/Complete/2025-09-25-UX-1-fix-visual-defects.md
projects/PROJECTA/PROJECTA_unity/.thoughts/Complete/MVP-2 Problem Engine/MVP-2 Plan.md
… +17 lines (ctrl+o to expand)
⏺ Bash(find projects/PROJECTA/PROJECTA_backend/.thoughts -type f -name "*.md" 2>/dev/null | head -20)
⎿ projects/PROJECTA/PROJECTA_backend/.thoughts/TODO.md
projects/PROJECTA/PROJECTA_backend/.thoughts/MVP-8 AWS/MVP-8 Plan.md
projects/PROJECTA/PROJECTA_backend/.thoughts/MVP-8 AWS/MVP-8 Updates.md
projects/PROJECTA/PROJECTA_backend/.thoughts/MVP-8 AWS/MVP-8 PRD.md
⏺ Bash(find projects/PROJECT/PROJECTB_web -type f -name "*.md" 2>/dev/null | head -20)
⎿ projects/PROJECTB/PROJECT_web/README.md
projects/PROJECTB/PROJECT_web/AGENTS.md
projects/PROJECTB/PROJECT_web/.aws/README.md
⎿ Loaded projects/PROJECTA/PROJECTA_unity/CLAUDE.md
⎿ Loaded projects/PROJECTA/PROJECTA_backend/CLAUDE.md
⎿ Loaded projects/PROJECT/CLAUDE.md
⎿ Loaded projects/PROJECT/PROJECTB_web/CLAUDE.md
⏺ Now let me check the AGENTS.md files in each submodule to understand their specific instructions:
⏺ Read(projects/PROJECTA/PROJECTA_unity/AGENTS.md)
⎿ Read 103 lines
⏺ Read(projects/PROJECTA/PROJECTA_backend/AGENTS.md)
⎿ Read 2 lines
⏺ Read(projects/PROJECTB/PROJECT_web/AGENTS.md)
⎿ Read 4 lines
⏺ Bash(ls -la projects/PROJECT)
⎿ drwxr-xr-x - ianwalker-sperber 19 Dec 04:30 .thoughts
.rw-r--r-- 154 ianwalker-sperber 19 Dec 04:32 AGENTS.md
lrwxr-xr-x - ianwalker-sperber 19 Dec 04:45 CLAUDE.md -> ./AGENTS.md
drwxr-xr-x - ianwalker-sperber 19 Dec 04:56 PROJECT_web
⏺ Let me also check the parent PROJECT project documentation and explore the PROJECTA parent folder:
⏺ Read(projects/PROJECTB/AGENTS.md)
⎿ Read 6 lines
⏺ Bash(ls -la projects/PROJECTA)
⎿ drwxr-xr-x - ianwalker-sperber 19 Dec 04:37 PROJECTA_backend
drwxr-xr-x - ianwalker-sperber 11 Dec 08:16 PROJECTA_unity
⏺ Search(pattern: "projects/*/README.md")
⎿ Found 0 files
⏺ I've successfully explored all active git submodules in your repository. Here's a summary of what I found:
Active Submodules (3):
Project Organization:
Each submodule contains:
Would you like me to perform any specific operations across these submodules, such as searching for specific code patterns, checking for consistency issues, or analyzing specific files?
⏺ I'll edit the README.md file in each of the three active submodules. Let me make simple improvements to each one.
⏺ Update(projects/PROJECTA/PROJECTA_unity/README.md)
⎿ Added 2 lines
1 # PROJECT A
2
3 +REDACTED.
4 +
5 See @AGENTS.md for game context.
6
7 ## Project Structure
⏺ Update(projects/PROJECTA/PROJECTA_backend/README.md)
⎿ Added 2 lines
1 # PROJECTA Backend
2
3 +Go-based AWS Lambda backend for PROJECTA game.
4 +
5 ## Scripts
6
7 ### build.sh
⏺ Update(projects/PROJECTB/PROJECT_web/README.md)
⎿ Added 4 lines
1 +# PROJECT Web
2 +
3 This is a Next.js project bootstrapped with
create-next-app.4
5 +REDACTED.
6 +
7 ## Getting Started
8
9 First, run the development server:
⏺ Successfully edited README.md files in all three active submodules:
All edits completed successfully, confirming full read/write access to files across all git submodules.
```
</details>
This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.
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.