claude-code - 💡(How to fix) Fix Worktree session creation fails with "not-a-git-repo" in repos containing git submodules

Summary

When creating a new local session with the "worktree" option enabled in a repository that contains git submodules, Claude Code creates the worktree successfully but then fails during the initial git checkout HEAD -- . step with not a git repository, then deletes the worktree and surfaces:

Background full checkout failed: not-a-git-repo

The session never opens. Disabling the "worktree" option works around the problem (session opens normally in the main checkout).

Repro

1. Have a repo with at least one git submodule (parent contains <submodule>/.git as a gitlink: gitdir: ../.git/modules/<submodule>).
2. In Claude Code desktop, start a new local session and tick "worktree".
3. Confirm.

Expected

Worktree is created and the session opens in it.

Actual

Worktree is created at <repo>/.claude/worktrees/<name>, then stageCheckout fails. The worktree is immediately removed and the UI shows Background full checkout failed: not-a-git-repo.

Log excerpt (~/Library/Logs/Claude/main.log)

[error] Git command failed: git -c filter.lfs.smudge= -c filter.lfs.process= \
  -c filter.lfs.required=false -c core.longpaths=true checkout HEAD -- . \
  :(exclude).claude {
  stderr: 'fatal: not a git repository: ../../../../.git/worktrees/<name>/modules/<submodule>\n
           fatal: could not reset submodule index\n',
  cwd: '<repo>/.claude/worktrees/<name>'
}
[error] Sentry caught: Background full checkout failed: not-a-git-repo
[warn] [CCD] first-turn init failed after worktree creation; removing orphaned worktree

Root cause (likely)

git worktree add does not provision submodule git directories under .git/worktrees/<name>/modules/<submodule>. The submodule's gitlink inside the worktree still resolves (relative) to the per-worktree modules dir, which does not exist, so the follow-up checkout that touches the submodule index fails with not a git repository.

This is the well-known git limitation that submodules and worktrees do not interoperate out of the box.

Workaround

Disable the "worktree" option in the new-session dialog. The session opens in the main checkout. This confirms the failure is isolated to the worktree provisioning path.

Suggested fix

After git worktree add, before running git checkout HEAD -- ., either:

• skip submodule reset for the staged checkout (git checkout --no-recurse-submodules or -c submodule.recurse=false),
• copy/symlink the parent repo's .git/modules/* into .git/worktrees/<name>/modules/* so submodule gitlinks resolve, or
• run git submodule absorbgitdirs / re-init submodules inside the worktree before the checkout.

The first option is the smallest change and unblocks repos that simply don't need submodules touched on session start.

Environment

• Claude Code (desktop): 2.1.138
• macOS: 26.3.1 (Darwin 25.3.0)
• git: 2.50.1 (Apple Git-155)
• Git config: extensions.worktreeconfig=true is enabled (mentioning in case it affects the staged-checkout path).
• Reproduced consistently in a repo with multiple submodules; same error recurring in local logs over a multi-week span.