Description

Claude Code creates stale .git/index.lock files from background git operations that block auto-worktree git commands and can contribute to worktree corruption.

Related Issue

This is related to an existing Claude Code bug: anthropics/claude-code#11005

Impact on Auto-Worktree

When using Claude Code with auto-worktree for parallel AI development:

• Background git status checks create lock files
• These locks persist if Claude Code crashes or is interrupted
• Subsequent auto-worktree operations fail with lock file errors
• Can contribute to worktree disappearance and corruption issues

Symptoms

$ auto-worktree <command>
fatal: Unable to create '.git/index.lock': File exists.

Another git process seems to be running in this repository...

Current Workarounds

# Manual lock file cleanup
find .git -name "*.lock" -delete

# Or specific cleanup
rm -f .git/index.lock
rm -f .git/worktrees/*/index.lock

Proposed Solutions

1. Auto-Cleanup on Operation Start

Auto-worktree should check for and remove stale lock files before operations:

func cleanStaleLocks(repoPath string) error {
    // Check lock file age
    // Verify no active git processes
    // Remove stale locks safely
}

2. Lock File Detection

Add auto-worktree doctor --check-locks command to detect and report stale locks.

3. Graceful Lock Waiting

Instead of immediately failing, wait briefly for locks to clear:

auto-worktree rebase --wait-for-locks --timeout 30s

4. Lock File Monitoring

Warn users when lock files are detected during initialization or health checks.

Integration Considerations

• Coordinate with Claude Code's background operations
• Don't remove locks from genuinely active processes
• Provide clear messaging about why operations are delayed
• Consider disabling Claude Code's background git operations when using auto-worktree

Related Resources

• Claude Code lock file bug: [BUG] Stale .git/index.lock files created by CC's background git operations block user git commands anthropics/claude-code#11005
• Git lock error guide: https://dev.to/rijultp/fixing-common-git-lock-errors-understanding-and-recovering-from-gitindexlock-47ej
• Git index.lock fix: https://www.khueapps.com/blog/article/how-to-fix-fatal-unable-to-create-git-index-lock-file-exists

Testing Needed

• Simulate Claude Code background operations
• Test lock detection with various lock file ages
• Verify safe removal of stale locks
• Test with genuinely active git processes