[BUG] MCP server and subagent processes not cleaned up on session end — orphan accumulation (macOS PPID=1)

[rolldav]

Summary

Claude Code does not terminate MCP server child processes or subagent processes when a session ends (normal exit, crash, or terminal close). On macOS, these become orphans with PPID=1 (adopted by launchd) and accumulate indefinitely.

This is a follow-up to #20369, #22612, #26658 with concrete reproduction data and a community workaround that confirms the root cause.

Environment

• Claude Code: 2.1.72+
• OS: macOS 26.3.1 (Darwin, Apple M4 Max)
• MCP servers: context7, supermemory, serena, playwright, greptile, typescript-lsp, dev-browser, + ~15 others

Observed behavior

After a typical workday with multiple Claude Code sessions:

• 107 unsigned node processes (PPID=1) — orphaned MCP servers
• 45 signed node processes (still active)
• Combined: ~7.75 GB RAM, ~40% CPU wasted
• Each npm exec MCP wrapper spawns 2 node processes, neither terminated on exit

Verified via: ps -eo pid,ppid,etimes,rss,comm | awk '$2==1'

Root cause (confirmed)

1. macOS lacks prctl(PR_SET_PDEATHSIG) — no native way to auto-kill children when parent dies
2. Claude Code does not track MCP server PIDs for cleanup on exit
3. MCP servers spawned via npm exec create 2 processes each (wrapper + node child), neither registered
4. SIGHUP is not forwarded to children on terminal close

The getOrCreateMcpConnection memoized function (identified in #22612) creates-instead-of-gets on disconnect, spawning duplicate servers and leaking PIDs.

Impact with OMC / Team mode

When using OMC (oh-my-claudecode) team N:role mode, each worker is a claude process spawned in a tmux pane. When the parent session dies:

• All tmux workers survive as orphans (PPID=1)
• Stop hooks do NOT fire for background agents (Background agents bypass Stop hooks #25147)
• This multiplies the leak: N workers × M MCP servers per worker

Community workarounds (confirmed working)

Three independent community projects have converged on the same solution:

• theQuert/cc-reaper: PGID group kill (Stop hook) + PPID=1 LaunchAgent daemon
• NathanSkene's claude-cleanup gist: PPID=1 + age guard + tree kill
• ImL1s/clean-orphans: PPID=1 + pattern whitelist

All use kill -- -$PGID (group kill) as primary method, PPID=1 scan as fallback.

Requested fix

Minimal (Stop hook support in core)

When Claude Code exits (any reason), send SIGTERM to its own process group:

process.on('exit', () => {
  try { process.kill(-process.getpgid(process.pid), 'SIGTERM'); } catch {}
});

Proper fix

1. Track spawned MCP server PIDs at session start
2. On session end (all exit paths including SIGHUP), iterate and SIGTERM each tracked PID
3. Use setpgrp() on spawned MCP processes to put them in the same process group
4. Add startup cleanup: detect MCP orphans from dead sessions (PPID=1 check)

Fix detection note

The community is monitoring CHANGELOG.md for keywords: orphan, PPID, process group, MCP.*clean, session.*cleanup to detect when this is addressed.

Related issues

• Orphaned subagent process leaks memory when parent terminal session terminated #20369 — Orphaned subagent process leaks memory
• Orphaned MCP server processes not cleaned up when sessions end #22612 — MCP servers not cleaned up when sessions end
• MCP server processes are never cleaned up when sessions end — orphan accumulation causes OOM #26658 — Orphan accumulation causes OOM (closed as duplicate)
• Background agents bypass Stop hooks #25147 — Background agents bypass Stop hooks

---

Reported with Claude Code + OMC v4.6.0 on macOS M4 Max

[ThinkOffApp]

We hit this running 9 concurrent agents on a Mac mini (M4, macOS 26.x). Our setup uses IDE Agent Kit to coordinate Claude Code sessions via tmux, so we see the multiplied version of this: each agent session leaks its MCP servers, and after a day of cycling sessions the machine is at 90%+ memory from orphaned node processes.

Our current workaround is a cron job that kills PPID=1 node processes older than 2 hours. The process group approach (kill -- -$PGID) from the community tools mentioned in the report is cleaner but we have not tried it yet since some of our MCP servers are shared across sessions.

The OMC/team mode interaction described here matches what we see with tmux-based agent coordination. Stop hooks not firing for background agents (#25147) is the root issue for us too.