[FEATURE] Native worktree support with submodules

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

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