claude-code - 💡(How to fix) Fix Mac app: 'Background full checkout failed: other' when starting worktree session (empty-index regression)

Summary

Starting a new Claude Code session in the Mac app with the worktree checkbox enabled fails with Background full checkout failed: other. The session aborts before the first turn. Unchecking the worktree box lets the session start normally. The failure is 100% reproducible across many attempts in the same repo.

Environment

• Mac app: Claude Code 2.1.121 (build path Claude/claude-code/2.1.121/claude.app)
• Platform: macOS (Darwin 25.3.0)
• Repo: ~3.8 GB working tree, ~108 MB .git, on branch main. Has many existing git worktrees (12 conductor worktrees + Claude-managed .claude/worktrees/<name>).
• Free disk: 55 GiB.
• LFS not installed (the failing command sets filter.lfs.* ).

User-visible error

Something went wrong Try sending your message again. If it keeps happening, share feedback so we can investigate.

Background full checkout failed: other

Root cause (from ~/Library/Logs/Claude/main.log)

The Mac app's worktree bootstrap consistently produces an empty index in the new worktree, then runs a git checkout that requires a non-empty index, so the pathspec match fails:

[stageCheckout] Selective checkout done in 19ms (0 paths)
[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:
    error: pathspec '.' did not match any file(s) known to git
    error: pathspec ':(exclude).claude' did not match any file(s) known to git
  cwd: <repo>/.claude/worktrees/<name>
[error] Sentry caught: { value: 'Background full checkout failed: other' }
[warn] [CCD] first-turn init failed after worktree creation; removing orphaned worktree

git checkout HEAD -- <pathspec> filters the pathspec against the index. When the prior "selective checkout" produced 0 paths, the index is empty, so . matches nothing and the command exits with the pathspec errors. The CCD bootstrap interprets the failure as fatal and tears the worktree down.

What changed

In the same log, an earlier successful session shows the working path:

[stageCheckout] Selective checkout done in 32ms (2 paths)
[stageCheckout] Background full checkout done in 638ms

After that point in the day, every subsequent worktree-mode start has logged Selective checkout done … (0 paths) and hit the failure above. The Mac app's heuristic for which paths to seed for the first turn appears to have started returning empty for this repo, exposing the latent bug.

Suggested fix

When the selective stage produces 0 paths, the background checkout should populate the worktree from HEAD without index-filtered pathspecs. Possible alternatives:

• git checkout HEAD -- (no pathspec — checks out HEAD into the working tree fully)
• git read-tree HEAD && git checkout-index -a -f then apply the .claude exclusion as a post-step
• git restore --source=HEAD --worktree --staged :/ followed by rm -rf .claude if needed

Any of these does not depend on index pre-population.

Workaround

Disable the worktree checkbox at session start. Sessions launched in-place work normally.

Logs

Happy to share fuller log excerpts if useful — full chain (selective checkout → failed background checkout → first-turn init failure → worktree removal) is logged at ~/Library/Logs/Claude/main.log.