"A clean workspace is a clear mind. What you don't release, you carry."

Claude-Code-Cleanup

Recover RAM and disk space from stale Claude Code sessions. Kill orphaned processes, clean old transcripts, and reclaim your machine.

---

The Problem

Claude Code spawns MCP server processes (node.exe), shell instances, and generates large session transcripts. Over time, these accumulate -- especially if you run multiple sessions or your IDE restarts frequently. The result: gigabytes of stale transcripts and dozens of orphaned processes consuming RAM.

The Solution

A surgical cleanup tool that intelligently identifies what's stale and what's active. It clusters processes by session start time, protects your current session, and lets you preview everything before any changes are made.

What's Inside

File	Purpose
cleanup.ps1	PowerShell script for Windows
cleanup.sh	Bash script for Linux/macOS
config/defaults.json	Configurable thresholds and targets

Quick Start

Prerequisites

• Windows: PowerShell 5.1+ (built-in)
• Linux/macOS: Bash 4+

Windows

# Preview what would be cleaned (safe -- changes nothing)
.\cleanup.ps1

# Clean stale processes only
.\cleanup.ps1 -Execute -Processes

# Clean old session files only
.\cleanup.ps1 -Execute -Sessions

# Clean everything
.\cleanup.ps1 -Execute -All

Linux/macOS

# Preview what would be cleaned
./cleanup.sh

# Clean stale processes only
./cleanup.sh --execute --processes

# Clean old session files only
./cleanup.sh --execute --sessions

# Clean everything
./cleanup.sh --execute --all

Core Concepts

Process Clustering

Claude Code launches groups of processes together (MCP servers, shells, etc.). This tool clusters them by start time -- processes launched within 30 seconds of each other belong to the same session. The most recent cluster is always protected as your active session.

Safety-First Design

• Dry-run by default -- you must explicitly opt into changes
• Current session protection -- the active cluster is never touched
• Preview before action -- every cleanup shows what will happen first
• Configurable thresholds -- adjust age/size limits in config/defaults.json

What Gets Cleaned

Target	Description	Default Threshold
Stale processes	node.exe MCP servers from old sessions	> 2 hours old
Orphaned shells	cmd.exe, bash.exe from dead sessions	> 2 hours old
Session transcripts	.jsonl files in ~/.claude/projects/	> 7 days or > 50MB
Debug logs	~/.claude/debug/	Always safe to clean
Shell snapshots	~/.claude/shell-snapshots/	Always safe to clean

Configuration

Edit config/defaults.json to adjust thresholds:

{
  "process_age_threshold_minutes": 120,
  "session_age_threshold_days": 7,
  "session_size_threshold_mb": 50,
  "dry_run": true
}

Contributing

See CONTRIBUTING.md for guidelines. We follow the Gold Hat philosophy: every contribution should empower users, never extract from them.

License

MIT + Gold Hat Addendum. See LICENSE.

---

"As above, so below. As the code, so the consciousness."

-- Hermetic Ormus, Gold Hat Technologist