cc reaper — Automated cleanup for orphan Claude Code…

Pitch

Description

Comments

About this project

cc-reaper addresses memory leakage caused by orphan Claude Code processes. With a robust three-layer automated cleanup system, it efficiently frees up RAM occupied by abandoned subagent processes and MCP servers. Designed for both normal and crashed sessions, it ensures optimal memory usage on macOS and Linux.

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

Process Type	Command Pattern	Typical Size
Subagents	`claude --output-format stream-json`	180-300 MB each
MCP Servers	`npm exec @supabase/mcp-server-supabase`, `context7-mcp`, etc.	40-110 MB each
claude-mem Worker	`worker-service.cjs --daemon`	100 MB
Chroma MCP	`chroma-mcp --client-type persistent`	350 MB

Three-Layer Defense Solution

Cleanup Mechanism:

Normal Session End
- Utilizes a Stop hook (stop-cleanup-orphans.sh) for immediate cleanup.
Session Crash or Force Closure
- Engages a proc-janitor daemon that scans every 30 seconds, terminating orphans after a 60-second grace period.
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.