Claude Desktop (macOS) hangs on quit — orphaned agent process ignores SIGTERM and survives app restart

Summary

Claude Desktop on macOS does not quit: the window stops responding and Force Quit is the only way out. Restarting the app does not fix it — the next quit hangs the same way. In my case this repeated for 3 days across multiple relaunches.

Root cause turned out to be an orphaned agent process that ignores SIGTERM.

Environment

• macOS (Darwin 25.5.0), Apple Silicon
• Claude Desktop, bundled claude-code 2.1.222
• Process: ~/Library/Application Support/Claude/claude-code/2.1.222/claude.app/Contents/MacOS/claude

Symptom

1. Quit Claude Desktop (Cmd+Q or window close) → UI becomes unresponsive, app never exits
2. Force Quit → app closes
3. Relaunch → quit hangs again, identically

Because the obvious remedy (restart the app) does not help, this initially looked like a random freeze rather than a persistent condition.

Root cause

An agent process survives as an orphan (PPID=1) and does not respond to SIGTERM. Shutdown appears to send SIGTERM to the child and wait for it indefinitely, so the app never reaches exit.

Evidence

$ ps -eo pid,ppid,stat,rss,lstart,command | grep -i claude

PID=33827  PPID=1  STAT=S  RSS=403MB  started "Aug  8 11:20:29 2026"   # still alive on Aug 11
   ~/Library/Application Support/Claude/claude-code/2.1.222/claude.app/Contents/MacOS/claude
   --permission-mode auto --permission-prompt-tool stdio ...

PID=89134  PPID=1  STAT=S  RSS=469MB  started "Aug 11 12:33:00 2026"   # freshly launched app,
                                                                       # hangs on quit anyway

The decisive signal — the process ignores the polite signal but dies instantly to the forced one:

$ kill 33827        # SIGTERM
   → process still alive

$ kill -9 33827     # SIGKILL
   → terminated immediately

This is presumably the same SIGTERM the app itself sends during shutdown, and it gets the same silence.

Why it persists across restarts

Force Quit terminates the parent app but leaves the agent process orphaned (reparented to PID 1). The next launch then runs alongside the stale agent, which still ignores SIGTERM — so quit hangs again.

Every Force Quit re-arms the trap. The same orphan (PID 33827) survived from Aug 8 to Aug 11 across multiple relaunches, holding 403 MB, until I killed it manually.

Reproduction

1. Use Claude Desktop until an agent session is running
2. Quit → hangs
3. Force Quit
4. Relaunch, quit again → hangs identically (repeatable)

Workaround

pkill -9 -f "claude-code/.*claude.app"

Killing the orphan restored normal quit behaviour immediately.

Suggested fix

1. On quit: escalate SIGTERM → SIGKILL after a short timeout instead of waiting on the child indefinitely.
2. On launch: detect and reap stale orphaned agent processes left over from previous sessions, so a Force Quit cannot poison subsequent runs.

Ruled out

For completeness, these were checked and are not the cause: no crash reports in ~/Library/Logs/DiagnosticReports, system memory 90% free with 0 MB swap in use, 685 GB free disk, no hung SSH or other child processes.