submodule-warning
Git Submodule — Always Run From Parent Root
Section titled “Git Submodule — Always Run From Parent Root”MANDATORY: Never launch Claude Code from inside a git submodule directory. settings.json does NOT inherit from parent projects — hooks, MCP servers, and skills/agents all resolve against CWD and go missing inside a submodule. CLAUDE.md alone walks up the tree; nothing else does.
| Scenario | Where to run Claude |
|---|---|
| Editing submodule files within parent project | Parent project root |
Submodule as standalone project (has own .claude/settings.json) | Submodule root |
| Any doubt | Parent project root |
Edit submodule files using relative paths (e.g., Packages/my-lib/...). For git operations on the submodule, use cd <submodule-path> && git ... in Bash commands.
Detection
Section titled “Detection”If you see MODULE_NOT_FOUND errors for .claude/hooks/ files during session start, the session was likely launched from inside a submodule. Exit and relaunch from the parent project root.