Automating the cleanup of orphaned Claude Code processes, cc-reaper addresses a critical issue in memory management. Orphan processes, such as subagents and MCP servers generated by Claude Code, can accumulate and consume substantial amounts of RAM after session terminations, especially in cases of crashes or abnormal closures.

Problem Overview

Claude Code creates separate subagent processes and MCP servers for each session, but when these sessions unexpectedly end, the resulting orphan processes (identified by PPID=1) continue to operate, leading to memory leaks. Typical memory consumption ranges from 200 MB to 400 MB per process, which can significantly impact system performance over time, potentially leading to excesses of 7 GB of memory wastage on a daily basis.

Types of Leaking Processes

Three-Layer Defense Solution

Cleanup Mechanism:

1. Normal Session End

   • Utilizes a Stop hook (stop-cleanup-orphans.sh) for immediate cleanup.

2. Session Crash or Force Closure

   • Engages a proc-janitor daemon that scans every 30 seconds, terminating orphans after a 60-second grace period.

3. Manual Intervention

   • Offers on-demand cleanup via claude-cleanup and RAM usage verification with claude-ram commands.

Usage Example

# View RAM usage breakdown
claude-ram

# Clean orphan processes immediately
claude-cleanup

Key Features

• Automated cleanup of orphan processes
• Real-time memory utilization monitoring
• User-friendly command options for on-demand cleanup

Project Structure

cc-reaper/
├── install.sh                      # Installer script
├── hooks/
│   └── stop-cleanup-orphans.sh     # Stop hook script
├── proc-janitor/
│   └── config.toml                 # Daemon configuration
├── shell/
│   └── claude-cleanup.sh           # Shell function scripts
└── README.md                        # Project documentation

Related Issues

• Orphan processes in Claude Code impacting system memory: Issue #20369
• Persistent subagent processes causing crashes on macOS: [Issue #22554](https://github.