Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

Many real-world repositories use Git submodules to manage shared libraries, infrastructure repositories, SDKs, or internal tooling.

Currently, when working with Git worktrees that contain submodules, Claude Code workflows become unreliable or difficult to manage because submodules are not handled consistently across worktree environments.

This creates friction in workflows such as:

parallel feature development hotfix + feature work at the same time multi-repository debugging testing changes across dependent repositories isolated experimental branches

In practice, developers often create separate worktrees for different tasks, but submodules inside those worktrees may:

not initialize correctly point to inconsistent states require manual reconfiguration break tooling assumptions confuse repository discovery/indexing

This becomes especially problematic in large monorepos or microservice ecosystems where submodules are part of the normal development workflow.

The current workaround requires manually managing submodule state for every worktree, which is error-prone and slows down development significantly.

Proposed Solution

Claude Code should provide native awareness and support for Git worktrees that contain submodules.

Ideal behavior could include:

correctly detecting repositories inside worktrees automatically recognizing submodules within the active worktree isolating context/indexing per worktree ensuring commands operate relative to the current worktree instead of the parent repository supporting nested repository discovery avoiding cache/index collisions between worktrees

Potential UX ideas:

automatic worktree detection explicit workspace/worktree selection indicators showing active worktree context commands to refresh or sync submodule state

Example:

claude

detects current worktree + submodules automatically

or

claude --worktree

or

claude --workspace ./frontend-worktree

Alternative Solutions

Current workarounds include:

manually opening separate Claude Code sessions duplicating repositories instead of using worktrees manually updating submodules in each worktree avoiding submodules entirely using multiple terminal windows and contexts

These approaches increase disk usage, create duplicated environments, and make context management harder.

Other development tools and IDEs generally treat worktrees as first-class Git environments and resolve submodules relative to the active worktree automatically.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Example scenario:

I'm working on a backend service that depends on a shared SDK stored as a Git submodule I create a worktree for a new feature branch I also create another worktree for a production hotfix Both worktrees need isolated submodule states Claude Code should understand each worktree independently and operate using the correct repository/submodule context This would allow safe parallel development without manually reconfiguring environments

Another common scenario:

A monorepo contains infrastructure modules as submodules Different worktrees are used for testing experimental changes Claude Code should correctly analyze/index only the repositories active inside that worktree This prevents context leakage and improves reliability

Additional Context

Git worktrees are becoming increasingly common in modern development workflows because they allow:

parallel task execution isolated branch environments safer experimentation reduced repository duplication

However, submodule support is essential for this workflow to work reliably in larger systems.

Native support would significantly improve developer experience for teams working with:

monorepos microservices shared SDKs infrastructure-as-code repositories polyrepo architectures