Last updated 13 October 2026
Access git submodules in Claude Code
Claude Code and submodule visibility
Claude Code uses standard file discovery tools to index your project. When you initiate a session with the claude command, the agent attempts to map out the structure of your repository. Git submodules present a specific challenge because they are separate repositories nested inside your main folder. If you have not initialized or updated your submodules, the agent sees an empty directory or a git commit hash. This prevents the Read and Edit tools from functioning on the code you actually need to change.
The agent strictly follows your .gitignore rules. Many developers ignore submodule contents or use configurations that hide nested git directories. If the agent cannot find your submodule files, verify that the files are physically present on your local machine. Use the claude doctor command to ensure the environment is healthy. If the files are there but invisible, the issue likely lies in how the agent perceives the directory boundaries or your local ignore settings.
Configuring global instructions
You can guide the agent by using CLAUDE.md files. Place a CLAUDE.md file in the root of your main repository to explain the relationship between the main project and its submodules. Tell the agent exactly where the important code lives. For example, explicitly state that the folder named library is a git submodule and contains the core logic for the API. This gives the agent a map to follow when it uses the Glob and Grep tools to find specific functions.
You can also place specific CLAUDE.md files inside the submodules themselves. This is useful when submodules have their own build systems or coding standards. A local CLAUDE.md in a subdirectory applies to that specific part of the tree. This ensures that when the agent enters that folder, it adopts the correct context. You might define how to run tests or explain that certain files should not be edited. This hierarchical configuration helps the agent stay oriented in complex, multi-repo environments.
Explicitly granting file access
Permissions play a critical role in how the agent handles submodules. By default, the agent might ask for permission every time it tries to write to a file in a new directory. You can streamline this by editing your settings.json file. Look for the file in the .claude folder at the root of your project. You can configure the permissions section to allow the Edit and Write tools to work automatically in specific submodule paths. This reduces the number of interruptions during a long task.
If you find yourself constantly approving changes in submodules, consider switching permission modes. You can press Shift+Tab to cycle through modes like acceptEdits or plan. The acceptEdits mode is particularly helpful when you trust the agent to refactor code across multiple submodules. If the agent refuses to touch a submodule file, check if it is blocked by a local override in .claude/settings.local.json. This file often contains personal settings that might differ from the main project configuration.
Navigating with shell tools
When the high-level tools fail to find a file in a submodule, you can direct the agent to use the Bash tool. The agent can run shell commands to list files or find specific strings across repository boundaries. If Glob does not return the expected results because of git configurations, a direct ls -R command through the Bash tool often works. This bypasses some of the indexing logic and shows the agent exactly what is on the disk.
Using the Grep tool is another effective way to bridge the gap between repositories. You can ask the agent to search for a function definition across the entire project including all submodules. Once the agent finds the file path through Grep, it can then use the Read tool to examine the contents. This manual discovery process is often necessary when the submodule structure is deeply nested. The agent is capable of following these paths once it knows they exist.
Managing multiple contexts
Large projects with many submodules can quickly fill the context window. Every file the agent reads and every command it runs stays in the current session context. Use the /compact command frequently to manage this. This command summarizes the session and frees up space, which is vital when you are jumping between different submodules. If the context becomes too cluttered with old file reads from a different repository, the agent might get confused about which version of a file it is looking at.
For very large changes involving multiple submodules, it is often better to use the /clear command and start fresh in a specific subdirectory. Running the claude command from within a submodule folder limits the agent's scope to just that repository. This reduces noise and ensures the agent focuses only on the relevant code. You can always use claude --resume or claude -r later to go back to a previous session in the main folder if you need to perform a top-level integration task.
Parallel workflows for complex repos
Managing multiple submodules simultaneously can be mentally taxing for a developer. This is where adhdTerminal provides a significant advantage. The app runs many Claude Code sessions side by side, with each one appearing as a tile on a wall. You can have one tile dedicated to the main repository and other tiles for each critical submodule. This setup allows you to see the state of every part of your project at once without losing track of your progress.
Each tile in adhdTerminal shows whether it is working, waiting, done, or idle. This is the honest answer when you need to coordinate complex changes across several repositories. You can monitor the last exchanges of each conversation and see headlines the project publishes. If you need to step away, the free iPhone app mirrors the wall over an end-to-end encrypted link. This lets you answer a prompt or send the next task to a specific submodule session from anywhere.
Troubleshooting permission errors
Sometimes the agent might encounter git lock files or permission errors when trying to use the Write tool inside a submodule. This usually happens if you have another git process running or if the submodule is in a detached HEAD state. You can ask the agent to use the Bash tool to check the status of the git repository. Commands like git status or checking the current branch help the agent understand why a file might be read-only or why a commit is failing.
If the agent gets stuck, use the Escape key to interrupt the current process. You can then press Escape twice to look at earlier messages and see where the communication regarding the submodule went wrong. Use the /doctor command if you suspect the issue is related to the Claude Code installation itself. Often, a simple update with claude update can resolve issues with how the agent interacts with complex file systems or newer git features.
Creating custom submodule commands
You can create custom commands to handle submodule tasks more efficiently. Create a markdown file in the .claude/commands directory to define a shortcut for common actions. For example, you could create a command that automatically pulls the latest changes for all submodules and runs a specific build script. This saves you from typing the same sequence of instructions every time you start a new session. It also ensures the agent follows a consistent process for updating the codebase.
Subagents are another powerful tool for multi-repository management. You can define subagents in .claude/agents that specialize in specific submodules. When the main agent needs to perform a task in a secondary repository, it can delegate that task to the appropriate subagent. This keeps the primary context clean and allows for more focused work. Using the /agents command inside a session will show you which specialized subagents are available to help with your submodule structure.
Questions people ask
Why does Claude Code say a file does not exist when it is in a submodule?
This usually happens because the submodule is not initialized or is hidden by your .gitignore file. Ensure the files are physically present on your disk and that your git settings allow the agent to see them. You can also use the Bash tool to verify the file path directly.
Can I edit files in multiple submodules in a single session?
Yes, the agent can use the Edit tool on any file it can reach, regardless of which repository it belongs to. However, large changes across many folders may fill your context window quickly. Use the /compact command to maintain performance when working on multi-repo tasks.
How do I prevent the agent from touching a specific submodule?
You can specify permissions in your .claude/settings.json file to restrict the Edit and Write tools for certain paths. Alternatively, you can add the submodule path to your .gitignore if you never want the agent to see those files. Setting a CLAUDE.md file in the subdirectory with restrictive instructions also helps.
Read next
- Allow Claude Code to run shell scriptsResolve tool execution errors by adjusting permission settings to let Claude Code execute local bash or powershell scripts in your terminal.
- Break a linter error loop in ClaudeWhat to do when Claude Code fixes one linting error only to create another, leading to a circular set of edits.
- Change the Node version for Claude CodeResolve compatibility issues by switching the Node.js version used by Claude Code without breaking your other local development tools.
- Claude Code cannot edit system filesHandle permission errors that occur when Claude Code attempts to modify files outside of the immediate project directory or in protected paths.