### Quick Start Installation

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Clone the repository and execute the installation script to set up the cleanup tools.

```bash
git clone https://github.com/theQuert/cc-reaper.git
cd cc-reaper
chmod +x install.sh
./install.sh
```

```bash
git pull
./install.sh
```

--------------------------------

### Install and Load macOS LaunchAgent

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Installs the orphan monitor LaunchAgent and loads it to start monitoring. Replace `__HOME__` with your actual home directory path.

```bash
sed "s|__HOME__|$HOME|g" launchd/com.cc-reaper.orphan-monitor.plist \
  > ~/Library/LaunchAgents/com.cc-reaper.orphan-monitor.plist
launchctl load ~/Library/LaunchAgents/com.cc-reaper.orphan-monitor.plist
```

--------------------------------

### Setup macOS LaunchAgent

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Install the native macOS monitor script to detect and clean up orphaned processes.

```bash
mkdir -p ~/.cc-reaper/logs
cp launchd/cc-reaper-monitor.sh ~/.cc-reaper/
chmod +x ~/.cc-reaper/cc-reaper-monitor.sh
```

--------------------------------

### Install proc-janitor using Homebrew or Cargo

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Installs the proc-janitor daemon, a feature-rich alternative to the LaunchAgent. Choose either Homebrew or Cargo for installation.

```bash
# Install
brew install jhlee0409/tap/proc-janitor   # or: cargo install proc-janitor

# Copy config
mkdir -p ~/.config/proc-janitor
cp proc-janitor/config.toml ~/.config/proc-janitor/config.toml
chmod 600 ~/.config/proc-janitor/config.toml
```

--------------------------------

### Clone and Install cc-reaper

Source: https://context7.com/thequert/cc-reaper/llms.txt

Use this command to clone the repository and run the one-command installer for cc-reaper. It configures shell functions, stop hooks, and the background daemon.

```bash
git clone https://github.com/theQuert/cc-reaper.git
cd cc-reaper
chmod +x install.sh
./install.sh
```

--------------------------------

### Install and manage LaunchAgent daemon

Source: https://context7.com/thequert/cc-reaper/llms.txt

Sets up a macOS native daemon to periodically detect and kill orphaned processes.

```bash
# Install LaunchAgent
mkdir -p ~/.cc-reaper/logs
cp launchd/cc-reaper-monitor.sh ~/.cc-reaper/
chmod +x ~/.cc-reaper/cc-reaper-monitor.sh

# Install plist with actual home path
sed "s|__HOME__|$HOME|g" launchd/com.cc-reaper.orphan-monitor.plist \
  > ~/Library/LaunchAgents/com.cc-reaper.orphan-monitor.plist
launchctl load ~/Library/LaunchAgents/com.cc-reaper.orphan-monitor.plist

# Check if running
launchctl list | grep cc-reaper
# Output: 12345  0  com.cc-reaper.orphan-monitor

# View cleanup log
cat ~/.cc-reaper/logs/monitor.log
# Output:
# 2024-03-24 10:30:00 KILL group PGID=12345 (PID=12345 CPU=0.1% MEM=2.3%)
# 2024-03-24 10:30:03 Cleaned 1 orphan process group(s)/process(es)

# Stop the daemon
launchctl unload ~/Library/LaunchAgents/com.cc-reaper.orphan-monitor.plist
```

--------------------------------

### Start proc-janitor Daemon

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Starts the proc-janitor daemon, either to auto-start on boot using Homebrew services or manually.

```bash
brew services start jhlee0409/tap/proc-janitor   # auto-start on boot
proc-janitor start                                # or manual
```

--------------------------------

### Update cc-reaper Installation

Source: https://context7.com/thequert/cc-reaper/llms.txt

Run these commands to update an existing cc-reaper installation to the latest version.

```bash
git pull
./install.sh
```

--------------------------------

### Configure claude-guard Thresholds

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Example of how to lower the resource thresholds for constrained machines by exporting environment variables before running claude-guard.

```bash
export CC_MAX_RSS_MB=2048
export CC_MAX_FD=5000
claude-guard
```

--------------------------------

### Configure proc-janitor daemon

Source: https://context7.com/thequert/cc-reaper/llms.txt

Manages the Rust-based daemon for process cleanup, including installation and configuration settings.

```bash
# Install proc-janitor
brew install jhlee0409/tap/proc-janitor
# Or: cargo install proc-janitor

# Copy and configure
mkdir -p ~/.config/proc-janitor
cp proc-janitor/config.toml ~/.config/proc-janitor/config.toml
chmod 600 ~/.config/proc-janitor/config.toml

# Edit config - replace ~ with actual home directory in log path
# vim ~/.config/proc-janitor/config.toml

# Start daemon
brew services start jhlee0409/tap/proc-janitor
# Or manually: proc-janitor start

# Useful commands
proc-janitor scan     # Dry run - show orphans without killing
proc-janitor clean    # Kill detected orphans
proc-janitor status   # Check daemon health
```

```toml
# ~/.config/proc-janitor/config.toml
scan_interval = 30      # Scan every 30 seconds
grace_period = 60       # Wait 60s before killing new orphans
sigterm_timeout = 5     # Wait 5s after SIGTERM before SIGKILL

targets = [
    "claude.*stream-json",
    "npm exec @upstash",
    "npm exec mcp-",
    "npx.*mcp-server",
    "node.*sequential-thinking",
    "worker-service.cjs.*--daemon",
    "bun.*worker-service",
]

whitelist = [
    "node.*(dev-server|http-server|next.*server)",
    "pm2",
    "npm exec @supabase",
    "npm exec @stripe",
    "context7-mcp",
    "claude-mem.*mcp-server",
    "chroma-mcp",
]

[logging]
enabled = true
path = "/Users/yourname/.proc-janitor/logs"
retention_days = 7
```

--------------------------------

### Install Claude Code Stop Hook

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Set up the stop hook script to automatically trigger cleanup when a session ends.

```bash
mkdir -p ~/.claude/hooks
cp hooks/stop-cleanup-orphans.sh ~/.claude/hooks/
chmod +x ~/.claude/hooks/stop-cleanup-orphans.sh
```

--------------------------------

### Useful Commands for macOS LaunchAgent

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Commands to check if the orphan monitor is running, view its logs, and stop it.

```bash
launchctl list | grep cc-reaper           # check if running
cat ~/.cc-reaper/logs/monitor.log         # view cleanup log
launchctl unload ~/Library/LaunchAgents/com.cc-reaper.orphan-monitor.plist  # stop
```

--------------------------------

### Configure Shell Functions

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Source the cleanup script in your shell configuration file to enable command-line utilities.

```bash
source /path/to/cc-reaper/shell/claude-cleanup.sh
```

--------------------------------

### Sync Configuration

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Manually update the proc-janitor configuration file after pulling updates.

```bash
cp proc-janitor/config.toml ~/.config/proc-janitor/config.toml
# Edit the log path: replace ~ with your actual home directory
```

--------------------------------

### Configure Claude Code Stop Hook

Source: https://context7.com/thequert/cc-reaper/llms.txt

Add this JSON configuration to your ~/.claude/settings.json file to enable the stop-cleanup-orphans.sh hook. This ensures that orphaned processes are cleaned up when a session ends normally.

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME\"/.claude/hooks/stop-cleanup-orphans.sh",
            "timeout": 15
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Claude Code Cleanup Commands

Source: https://github.com/thequert/cc-reaper/blob/main/CLAUDE.md

Post-installation commands for monitoring and managing Claude Code processes.

```bash
claude-ram              # Show RAM usage by process category
claude-fd               # Show file descriptor usage per session + VM processes
claude-sessions         # List active sessions with idle/bloated status
claude-cleanup          # Kill orphan processes immediately
claude-guard            # Auto-reaper: kills bloated (>CC_MAX_RSS_MB) and excess idle sessions
claude-guard --dry-run  # Preview what claude-guard would kill
proc-janitor scan       # Dry-run orphan detection
proc-janitor clean      # Kill detected orphans
proc-janitor status     # Check daemon health
```

--------------------------------

### Display RAM and CPU Usage Breakdown

Source: https://context7.com/thequert/cc-reaper/llms.txt

Run the `claude-ram` command to see a detailed breakdown of RAM and CPU usage for all Claude Code processes, including sessions, subagents, MCP servers, and orphans. It helps identify memory leaks.

```bash
claude-ram
```

--------------------------------

### Manage Claude sessions with claude-guard

Source: https://context7.com/thequert/cc-reaper/llms.txt

Controls session reaping based on resource usage thresholds like RSS, file descriptors, and idle time.

```bash
# Run guard with default settings
claude-guard
```

```bash
# Preview without killing
claude-guard --dry-run
```

```bash
# Custom thresholds for constrained machines
export CC_MAX_RSS_MB=2048    # Kill sessions over 2GB tree RSS
export CC_MAX_FD=5000        # Kill sessions with >5000 file descriptors
export CC_MAX_SESSIONS=2     # Max 2 concurrent sessions
export CC_IDLE_THRESHOLD=1   # CPU% below which session is idle
claude-guard
```

--------------------------------

### Run claude-guard

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Executes the claude-guard to kill bloated sessions and excess idle sessions. Use `--dry-run` to preview actions without killing.

```bash
claude-guard            # run the guard (kills bloated + excess idle)
claude-guard --dry-run  # preview without killing
```

--------------------------------

### Add cc-reaper Shell Functions to Profile

Source: https://context7.com/thequert/cc-reaper/llms.txt

Source the cc-reaper cleanup script into your shell profile (~/.zshrc or ~/.bashrc) to enable manual cleanup commands. Remember to reload your shell after adding the line.

```bash
source /path/to/cc-reaper/shell/claude-cleanup.sh
```

```bash
source ~/.zshrc
```

--------------------------------

### List Active Claude Code Sessions

Source: https://context7.com/thequert/cc-reaper/llms.txt

Use the `claude-sessions` command to list all active Claude Code sessions. It includes idle detection, process tree RAM usage, and child process counts, helping to manage active and idle sessions.

```bash
claude-sessions
```

--------------------------------

### Implement stop hook script

Source: https://context7.com/thequert/cc-reaper/llms.txt

Automates cleanup when a session ends by identifying the process group ID.

```bash
#!/bin/bash
# ~/.claude/hooks/stop-cleanup-orphans.sh

# Whitelist: Long-running MCP servers shared across sessions
MCP_WHITELIST="supabase|@stripe/mcp|context7|claude-mem|chroma-mcp"

# Get session's process group ID
SESSION_PGID=$(ps -o pgid= -p $$ 2>/dev/null | tr -d ' ')
```

--------------------------------

### Useful Commands for proc-janitor

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Commands to perform a dry run scan, clean up detected orphans, and check the daemon's health.

```bash
proc-janitor scan     # dry run — show orphans without killing
proc-janitor clean    # kill detected orphans
proc-janitor status   # check daemon health
```

--------------------------------

### Display File Descriptor Usage

Source: https://context7.com/thequert/cc-reaper/llms.txt

Execute `claude-fd` to view file descriptor usage for Claude Code sessions and VirtualMachine processes. This command is useful for detecting file descriptor leaks, which can impact system stability.

```bash
claude-fd
```

--------------------------------

### Kill Orphan Claude Code Processes

Source: https://context7.com/thequert/cc-reaper/llms.txt

Run `claude-cleanup` to immediately kill orphan Claude Code processes. This command uses PGID-based group cleanup with a pattern-based fallback for comprehensive orphan removal.

```bash
claude-cleanup
```

--------------------------------

### Register Stop Hook in settings.json

Source: https://github.com/thequert/cc-reaper/blob/main/README.md

Add the stop hook command to the Claude Code settings file.

```json
{
  "type": "command",
  "command": "\"$HOME\"/.claude/hooks/stop-cleanup-orphans.sh",
  "timeout": 15
}
```

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME\"/.claude/hooks/stop-cleanup-orphans.sh",
            "timeout": 15
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Terminate Process Group and Orphaned Claude Processes

Source: https://context7.com/thequert/cc-reaper/llms.txt

This script kills processes within a specific group while respecting a whitelist, followed by a fallback pattern-based cleanup for specific Claude-related processes.

```bash
if [ -n "$SESSION_PGID" ] && [ "$SESSION_PGID" != "0" ]; then
  while IFS= read -r pid; do
    [ -z "$pid" ] && continue
    pid_cmd=$(ps -o command= -p "$pid" 2>/dev/null)
    if echo "$pid_cmd" | grep -qE "$MCP_WHITELIST"; then
      continue  # Skip whitelisted MCP servers
    fi
    kill "$pid" 2>/dev/null
  done < <(ps -eo pid,pgid 2>/dev/null | awk -v pgid="$SESSION_PGID" \
    -v me="$$" -v parent="$PPID" \
    '$2 == pgid && $1 != me && $1 != parent {print $1}')
fi

# Pattern-based fallback for escaped processes
ps aux | grep "[c]laude.*stream-json" | awk '$7 == "??" {print $2}' | xargs kill 2>/dev/null

echo "[cleanup] Orphan Claude processes cleaned up."
exit 0
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.