Claude Code Cleaner

Claude Code Cleaner

Diagnose and fix slow Claude Code startup caused by accumulated configuration files.

GLOBAL IMPACT WARNING

This command modifies ~/.claude - Claude Code's configuration directory.

Backup Location

All backups are stored in: ~/.claude-backups/

~/.claude-backups/
├── 2025-01-18T15-30-00/
│   ├── manifest.json          # What was backed up and why
│   ├── claude.json            # If auth-config was reset
│   └── projects.tgz           # If sessions were pruned
├── 2025-01-17T10-00-00/
│   └── ...
└── latest -> 2025-01-18T15-30-00/  # Symlink to most recent

EXCLUDED FROM TEST-PLUGIN

DO NOT test this command via /test-plugin. It is explicitly excluded because:

• Running it automatically could destroy the session running the tests
• There's no safe way to test "delete files from ~/.claude" in CI

When to Use

• Claude Code takes a long time to start
• Disk space is low due to ~/.claude growth
• Performance degrades over time
• Error messages about Grove timeout or PowerShell

Modes

Available Actions

CRITICAL SAFETY PROTOCOL

1. ALWAYS Use AskUserQuestion Before Destructive Actions

WRONG: Just run the command
python3 cc-cleaner-fix.py DELETE-plugin-cache --confirm

RIGHT: Preview first, ask, then confirm
1. python3 cc-cleaner-fix.py DELETE-plugin-cache       # Preview
2. Show preview to user with AskUserQuestion
3. Only if user confirms:
   python3 cc-cleaner-fix.py DELETE-plugin-cache --confirm

2. Show File Preview Before Any Deletion

Present to user:

• Exact file paths that will be deleted
• Size of each file/directory
• Age of files (for session/log cleanup)
• Total size to be freed
• Backup location

3. Verify Backup Before Confirming Success

After running with --confirm, check:

• Backup directory exists in ~/.claude-backups/
• manifest.json was created
• Report backup path to user with restore command

Interactive Workflow (/clean)

Step 1: Warning Banner

Display the global impact warning prominently.

Step 2: Run Scan

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/cc-cleaner-scan.py" --json

Parse JSON to get:

• metrics: sizes and file counts
• findings: issues found with risk levels
• actions: recommended actions with file previews

Step 3: Display Results

Show:

• Total ~/.claude size
• ~/.claude.json size
• Findings table with [CRITICAL], [HIGH], [MEDIUM], [LOW] labels
• File counts and sizes for each finding

Step 4: User Selects Actions

Use AskUserQuestion with multiSelect to let user choose which actions:

Header: "Select Actions"
Question: "Which issues do you want to fix? (Backups created for all)"
Options (multiSelect: true):
  - "DELETE-plugin-cache (2.1 GB) - plugins re-download on use"
  - "DELETE-old-sessions (156 MB) - removes sessions >30 days"
  - "DELETE-debug-logs (45 MB)"

Step 5: Preview Selected Actions

For each selected action, show detailed preview:

Preview of DELETE-plugin-cache:

Files to be deleted:
  ~/.claude/plugins/cache/bluera/bluera-base/0.14.0  (180 MB)
  ~/.claude/plugins/cache/bluera/bluera-knowledge/0.17.1  (1.9 GB)
  ... (10 more plugins)

Total: 12 plugins, 2.1 GB
Backup: ~/.claude-backups/2025-01-18T15-30-00/

Step 6: Final Confirmation

Use AskUserQuestion:

Header: "Confirm Deletion"
Question: "Delete 2.3 GB across 2 actions? Backup will be created first."
Options:
  - "Yes, backup and delete"
  - "No, cancel everything"

Step 7: Execute with Progress

# For each confirmed action:
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/cc-cleaner-fix.py" <action> --confirm --json

Report results:

• What was deleted
• Size freed
• Backup location
• Restore command

Scan Mode (/clean scan)

Read-only scan:

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/cc-cleaner-scan.py"

If issues found, suggest:

• /clean for interactive cleanup
• /clean fix <action> for specific fixes

Fix Mode (/clean fix <action>)

Single action with preview and confirmation:

# Step 1: Preview (default - no --confirm)
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/cc-cleaner-fix.py" <action> --json

# Step 2: Show preview to user via AskUserQuestion

# Step 3: Execute (only after user confirms)
python3 "${CLAUDE_PLUGIN_ROOT}/scripts/cc-cleaner-fix.py" <action> --confirm --json

Options:

• --days N: Days threshold for session/log cleanup (default: 30 for sessions, 14 for logs)
• --json: Output JSON for parsing
• --confirm: Actually execute (preview mode by default)

Backup Management

List Backups

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/cc-cleaner-fix.py" list-backups --json

Shows all backups with:

• Timestamp
• Action that created it
• Size
• Files backed up

Restore from Backup

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/cc-cleaner-fix.py" restore-backup --timestamp 2025-01-18T15-30-00

Restores all files from the specified backup.

Common Issues

Plugin Cache Bloat (GB+ common)

Symptoms: Massive ~/.claude/plugins/cache directory

Cause: Plugin cache accumulates multiple versions

Fix: DELETE-plugin-cache - plugins re-download on next use

Warning: Running plugins will break mid-session!

Projects Directory Bloat

Symptoms: Large ~/.claude/projects with many files

Cause: Session files accumulate over time

Fix:

• set-cleanup-period --days 7 - auto-delete old sessions at startup
• DELETE-old-sessions --days 30 - manual cleanup with backup

Large ~/.claude.json

Symptoms: ~/.claude.json grows to MB/GB

Cause: History accumulates

Fix: DELETE-auth-config - backup and disable (requires re-login)

Grove Timeout Errors

Symptoms: Debug logs show "Grove notice config" timeout

Cause: Network configuration issues

Fix: disable-nonessential - disable non-essential network traffic

Risk Levels

Typical Sizes

File Locations

~/.claude/                    # Main config directory
├── settings.json             # User settings
├── plugins/cache/            # Plugin cache (safe to delete)
├── projects/                 # Session files per project
├── debug/                    # Debug logs
└── CLAUDE.md                 # User's global memory file

~/.claude.json                # Authentication & history

~/.claude-backups/            # Centralized backup location
├── YYYY-MM-DDTHH-MM-SS/      # Timestamped backup directories
│   ├── manifest.json         # Backup metadata
│   └── ...                   # Backed up files
└── latest -> ...             # Symlink to most recent

Environment Variables

• CLAUDE_CONFIG_DIR: Override ~/.claude location
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: Disable telemetry