Git process zombies causing sessions to hang mid-task

Claude Code Bug Report: Git Process Zombies Causing Session Hangs

Summary

Claude Code sessions frequently "stop" mid-task without completion detection, requiring manual "Stop" button intervention. Root cause: Git child processes become zombies and are not properly reaped, causing Claude Code to hang waiting for process completion.

Environment

• Claude Code Version: 2.0.25
• Model: claude-sonnet-4-5-20250929
• OS: Linux 6.8.0-31-generic (Ubuntu)
• Date: 2025-10-22

Symptoms

1. Claude Code appears to hang mid-task with no progress
2. UI shows "thinking" or "working" but no updates
3. Completion not detected - user must manually hit "Stop"
4. Very frequent session churn (~54 temp files in 60 minutes)
5. Git operations occasionally fail with lock file conflicts

Root Cause

Git commands spawned through bash wrapper (/bin/bash -c -l) are not being properly reaped after completion, resulting in zombie processes. Claude Code appears to wait for these processes, causing perceived hangs.

Evidence

1. Multiple Zombie Git Processes Detected

# First zombie (already reaped by time of check)
claude  71455  0.0  0.0      0     0 pts/0    Z+   00:04   0:00 [git] <defunct>

# Second zombie appeared during investigation
claude  72649  0.0  0.0      0     0 pts/0    Z+   00:05   0:00 [git] <defunct>

# Third zombie
claude  74346  0.0  0.0      0     0 pts/0    Z+   00:19   0:00 [git] <defunct>

2. Git Lock File Conflicts (from claudecodeui logs)

Oct 21 23:53:24 devBot1 claudecodeui[66837]: fatal: Unable to create '/home/claude/projects/BG-Web/.git/index.lock': File exists.

Another git process seems to be running in this repository, e.g.
an editor opened by 'git commit'. Please make sure all processes
are terminated then try again.

3. High Session Churn Rate

$ find /tmp -name "claude-*-cwd" -mmin -60 | wc -l
54

This indicates approximately 1 new session per minute, suggesting frequent crashes/hangs/restarts.

4. Git Commands Run Through Bash Wrapper

Git operations are executed via:

/bin/bash -c -l source /home/claude/.claude/shell-snapshots/snapshot-bash-*.sh && eval 'git ...'

The additional shell wrapper layer may be preventing proper SIGCHLD signal handling.

Reproduction Steps

1. Start a Claude Code session
2. Perform git operations (status, diff, commit)
3. Observe zombie git processes appearing: ps aux | grep "git.*defunct"
4. Session eventually appears to hang
5. Manual intervention required

Expected Behavior

• Git child processes should be properly reaped immediately after completion
• No zombie processes should persist
• Claude Code should detect task completion and continue
• Sessions should not appear to hang

Actual Behavior

• Git processes become zombies
• Zombies persist until eventually reaped by parent
• Claude Code waits indefinitely during zombie window
• UI does not detect completion
• Users must manually stop sessions

Technical Analysis

Likely Causes:

1. Async/await handling: Git commands may be spawned without proper promise/callback handling
2. SIGCHLD signals: Parent process not setting up SIGCHLD handlers to reap children
3. Shell wrapper complexity: Bash wrapper adds process layer that complicates lifecycle management
4. waitpid() missing: No explicit call to reap child processes

Affected Operations:

• git status
• git diff
• git commit
• git add
• Any git operation spawned through bash wrapper

Suggested Fixes

Short-term:

1. Add explicit SIGCHLD signal handlers to reap zombie processes immediately
2. Use waitpid() or equivalent after spawning git processes
3. Add timeout handling for git operations (30-60 seconds)

Medium-term:

1. Simplify bash wrapper to reduce process layers
2. Use direct process spawning (not through shell) where possible
3. Implement process pool with proper lifecycle management

Long-term:

1. Review all child process spawning across Claude Code
2. Implement comprehensive process monitoring and cleanup
3. Add telemetry to detect and report zombie processes
4. Add UI indicators when waiting for external processes

Impact

Severity: High

• Affects core git functionality
• Causes frequent session interruptions
• Degrades user experience significantly
• Requires manual intervention to recover

Additional Context

System Resources (normal):

• Memory: 180GB available (plenty)
• CPU: ~5% usage (not resource constrained)
• Disk: Normal

Network:

• GitHub CLI (gh) authentication working
• Git network operations successful when they complete
• Not a credential or network timeout issue

Files for Review

Suggested areas to audit in Claude Code source:

• Child process spawning logic
• Bash command execution wrapper
• SIGCHLD signal handling
• Process cleanup/reaping code
• Git operation implementation

Reproduction Rate

Very High - Multiple zombie processes observed within minutes of investigation, high session churn rate confirms this is a frequent/consistent issue.

---

Reporter: System analysis via Claude Code
Date: 2025-10-22
Investigation Duration: 20 minutes
Zombie Processes Found: 3 distinct instances