shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程无需 API Key

claude-code-cleaner

诊断Claude Code启动缓慢的问题，并指导清理。使用/bluera-base:claude-code-clean运行。

person作者: jakexiaohubgithub
open_in_new仓库download下载资源包

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.

| Risk | Consequence | |------|-------------| | Kills running plugins | Clearing cache invalidates all cached plugins MID-SESSION. Hooks stop working immediately. | | Global scope | Changes affect EVERY project, not just the current one | | Can corrupt config | Bad writes to settings.json or .claude.json can break Claude entirely |

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

| Mode | Purpose | |------|---------| | /clean | Interactive wizard with guided cleanup | | /clean scan | Read-only scan, no changes | | /clean fix <action> | Single action with preview and confirmation | | /clean backups list | List available backups | | /clean backups restore <timestamp> | Restore from a backup |

Available Actions

| Action | Safety | Description | |--------|--------|-------------| | DELETE-plugin-cache | CAUTION | Remove plugin cache (plugins re-download on use) | | DELETE-old-sessions | DESTRUCTIVE | Delete session files older than N days | | DELETE-debug-logs | SAFE | Delete debug log files older than N days | | DELETE-auth-config | DESTRUCTIVE | Backup and disable ~/.claude.json (requires re-login) | | disable-nonessential | CAUTION | Set CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 | | set-cleanup-period | SAFE | Set auto-cleanup period in settings.json |

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

| Level | Meaning | Example Actions | |-------|---------|-----------------| | SAFE | No risk of data loss | DELETE-debug-logs, set-cleanup-period | | CAUTION | May affect running session | DELETE-plugin-cache, disable-nonessential | | DESTRUCTIVE | Deletes user data | DELETE-old-sessions, DELETE-auth-config |

Typical Sizes

| Path | Normal | Concerning | Critical | |------|--------|------------|----------| | ~/.claude total | <1GB | >5GB | >20GB | | ~/.claude.json | <100KB | >5MB | >100MB | | plugins/cache | <100MB | >1GB | >10GB | | projects/ | <500MB | >2GB | >10GB |

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