Claude-skill-registry claude-cleaner

Diagnose slow Claude Code startup and guide cleanup. Use /bluera-base:clean to run.

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/claude-cleaner" ~/.claude/skills/majiayu000-claude-skill-registry-claude-cleaner && rm -rf "$T"

manifest: skills/data/claude-cleaner/SKILL.md

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

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

Claude-skill-registry claude-cleaner

Claude Code Cleaner

GLOBAL IMPACT WARNING

Backup Location

EXCLUDED FROM TEST-PLUGIN

When to Use

Modes

Available Actions

CRITICAL SAFETY PROTOCOL

1. ALWAYS Use AskUserQuestion Before Destructive Actions

2. Show File Preview Before Any Deletion

3. Verify Backup Before Confirming Success

Interactive Workflow (
`/clean`
)

Step 1: Warning Banner

Step 2: Run Scan

Step 3: Display Results

Step 4: User Selects Actions

Step 5: Preview Selected Actions

Step 6: Final Confirmation

Step 7: Execute with Progress

Scan Mode (
`/clean scan`
)

Fix Mode (
`/clean fix <action>`
)

Backup Management

List Backups

Restore from Backup

Common Issues

Plugin Cache Bloat (GB+ common)

Projects Directory Bloat

Large ~/.claude.json

Grove Timeout Errors

Risk Levels

Typical Sizes

File Locations

Environment Variables

Claude-skill-registry claude-cleaner

Claude Code Cleaner

GLOBAL IMPACT WARNING

Backup Location

EXCLUDED FROM TEST-PLUGIN

When to Use

Modes

Available Actions

CRITICAL SAFETY PROTOCOL

1. ALWAYS Use AskUserQuestion Before Destructive Actions

2. Show File Preview Before Any Deletion

3. Verify Backup Before Confirming Success

Interactive Workflow (/clean)

Step 1: Warning Banner

Step 2: Run Scan

Step 3: Display Results

Step 4: User Selects Actions

Step 5: Preview Selected Actions

Step 6: Final Confirmation

Step 7: Execute with Progress

Scan Mode (/clean scan)

Fix Mode (/clean fix <action>)

Backup Management

List Backups

Restore from Backup

Common Issues

Plugin Cache Bloat (GB+ common)

Projects Directory Bloat

Large ~/.claude.json

Grove Timeout Errors

Risk Levels

Typical Sizes

File Locations

Environment Variables

Interactive Workflow (
`/clean`
)

Scan Mode (
`/clean scan`
)

Fix Mode (
`/clean fix <action>`
)