Starting a thread with "new worktree" runs git worktree add, which never populates submodules. The worktree is missing whatever they contain, with no indication anything is absent.
Why it hurts
Repositories that keep shared agent tooling in a submodule lose it in every worktree. In my case .agents/shared is a submodule holding skills that .claude/skills/* symlinks into, so each new worktree had ten dangling symlinks:
diagnosing-bugs feature-across-repos fix-code git-worktrees re-release-version
resolve-pr-comments resolving-merge-conflicts ship updating-shared-agent-rules verify-local
Skill discovery skips an unreadable SKILL.md, so the skills simply vanish from the picker. Running one reported Unknown command, which is accurate but gives no hint that the cause is an unpopulated submodule.
Probing the Agent SDK for available commands shows the gap directly:
| cwd |
commands |
| repository root |
98 |
| new worktree |
88 |
Same repo, same branch content; the 10 missing entries are exactly the submodule-backed skills.
Expected
A worktree should match a fresh checkout of the same ref. git submodule update --init --recursive after worktree add fixes it, and costs ~90 ms offline because the objects are normally already in the parent's .git/modules. It needs to stay best-effort — a first-ever clone needs the network, and an unreachable submodule should not fail thread creation.
Reproduce
- Use a repository with a submodule.
- Start a thread with "new worktree".
- The submodule path in the new worktree is empty.
Environment
macOS, git 2.x.
Starting a thread with "new worktree" runs
git worktree add, which never populates submodules. The worktree is missing whatever they contain, with no indication anything is absent.Why it hurts
Repositories that keep shared agent tooling in a submodule lose it in every worktree. In my case
.agents/sharedis a submodule holding skills that.claude/skills/*symlinks into, so each new worktree had ten dangling symlinks:Skill discovery skips an unreadable
SKILL.md, so the skills simply vanish from the picker. Running one reportedUnknown command, which is accurate but gives no hint that the cause is an unpopulated submodule.Probing the Agent SDK for available commands shows the gap directly:
Same repo, same branch content; the 10 missing entries are exactly the submodule-backed skills.
Expected
A worktree should match a fresh checkout of the same ref.
git submodule update --init --recursiveafterworktree addfixes it, and costs ~90 ms offline because the objects are normally already in the parent's.git/modules. It needs to stay best-effort — a first-ever clone needs the network, and an unreachable submodule should not fail thread creation.Reproduce
Environment
macOS, git 2.x.