Housekeeping

Claude Housekeeping - Configuration Cleanup & Optimization

This skill performs comprehensive audits of Claude configuration folders to identify waste, redundancy, and optimization opportunities.

Parameters

• scope: user (default) | project | all
• user: Analyzes ~/.claude (global user configuration)
• project: Analyzes .claude in current working directory
• all: Analyzes both locations

Workflow

Phase 1: Discovery - Leave No Stone Unturned

Systematically scan the target directory for all configuration artifacts:

1.1 Hooks Analysis

# Find all hook files
find <target> -name "*.js" -path "*/hooks/*" -type f
find <target> -name "*.ts" -path "*/hooks/*" -type f

For each hook, analyze:

• Token efficiency: Does it inject large context on every invocation?
• Execution frequency: Pre-tool, post-tool, session hooks - how often does it fire?
• Output size: How much data does it add to context?
• Redundancy: Does it duplicate information available elsewhere?
• Error handling: Silent failures that waste processing?

1.2 Commands Analysis

find <target> -name "*.md" -path "*/commands/*" -type f

For each command:

• Usage patterns: Is it ever invoked?
• Token cost: How large is the command definition?
• Duplication: Does it overlap with built-in or plugin commands?
• Optimization: Can prompts be more concise?

1.3 Plugins Analysis

ls -la <target>/plugins/

Analyze:

• Cache bloat: Multiple versions cached? Old temp directories?
• Unused plugins: Installed but never invoked?
• Duplicate functionality: Multiple plugins doing same thing?
• MCP server configs: Orphaned or broken configurations?

1.4 Storage Analysis

du -sh <target>/*
find <target> -type f -size +100k
find <target> -name "*.log" -o -name "*.jsonl"

Identify:

• Log files: Accumulating without rotation?
• Cache directories: Stale or oversized?
• Session files: Old sessions cluttering storage?
• Backup files: .bak, .backup, copy files?
• Temp files: Orphaned temporary artifacts?

1.5 Settings & Configuration

cat <target>/settings.json
cat <target>/.mcp.json
cat <target>/CLAUDE.md

Check for:

• Outdated settings: Old model references, deprecated options?
• MCP server bloat: Too many servers configured?
• CLAUDE.md size: Is it too large for efficient context loading?
• Duplicate configurations: Same settings in multiple places?

1.6 Rules & Agents

find <target> -path "*/rules/*" -type f
find <target> -path "*/agents/*" -type f

Analyze:

• Rule conflicts: Overlapping or contradictory rules?
• Agent redundancy: Multiple agents with similar purposes?
• Token overhead: Verbose rules that could be condensed?

Phase 2: Analysis & Metrics

For each discovered item, calculate:

1. Token Cost

• File size in characters → approximate token count (÷4)
• Frequency of loading into context
• Total token impact per session

2. Storage Impact

• Disk space consumed
• Growth rate (if logs/caches)

3. Value Assessment

• Is this actively used?
• Does it provide unique value?
• Could it be consolidated with something else?

4. Risk Rating

• SAFE: Can remove without any impact
• LOW: Minimal risk, unlikely to affect functionality
• MEDIUM: May affect some workflows, backup recommended
• HIGH: Core functionality, careful review needed

Phase 3: Action Plan Generation

Compile findings into a structured action plan:

# Claude Housekeeping Report
**Scope**: [user/project/all]
**Analyzed**: [timestamp]
**Total Files Scanned**: [count]

## Executive Summary
- Total potential token savings: ~[X]k tokens/session
- Storage recoverable: [X] MB
- Items requiring attention: [count]

## Priority Actions

### 🔴 High Priority (Immediate token savings)
| Item | Current Impact | Action | Savings |
|------|---------------|--------|---------|
| [file/item] | [X] tokens/load | [action] | [benefit] |

### 🟡 Medium Priority (Optimization opportunities)
| Item | Current Impact | Action | Savings |
|------|---------------|--------|---------|

### 🟢 Low Priority (Nice to have)
| Item | Current Impact | Action | Savings |
|------|---------------|--------|---------|

## Detailed Findings

### Hooks ([count] found)
[Per-hook analysis with specific recommendations]

### Commands ([count] found)
[Per-command analysis]

### Plugins ([count] found)
[Plugin cache and configuration analysis]

### Storage ([size] total)
[Storage breakdown and cleanup opportunities]

### Configuration
[Settings optimization opportunities]

## Before/After Comparison

| Metric | Before | After | Improvement |
|--------|--------|-------|-------------|
| Context overhead | [X] tokens | [X] tokens | -[X]% |
| Disk usage | [X] MB | [X] MB | -[X]% |
| Startup time | [estimated] | [estimated] | [improvement] |

## Recommended Actions

Select which actions to perform:
1. [ ] [Action 1 - description]
2. [ ] [Action 2 - description]
...

Phase 4: Interactive Execution

After presenting the plan, wait for user selection:

1. User selects items by number or category 2. Confirm before destructive actions - especially for HIGH risk items 3. Create backups before removing anything with MEDIUM+ risk 4. Execute incrementally - one action at a time with verification 5. Report results after each action

Common Optimization Patterns

Hook Token Waste Patterns

Command Optimization Patterns

Storage Cleanup Patterns

Safety Protocols

1. Never delete without backup: Create .housekeeping-backup/ before removing 2. Confirm high-risk actions: Always ask before touching core configs 3. Incremental changes: One action at a time, verify after each 4. Rollback capability: Keep backup until user confirms success 5. Dry-run option: Show what would happen without doing it

Usage Examples

/housekeeping                    # Analyze ~/.claude (default)
/housekeeping scope=project      # Analyze .claude in current project
/housekeeping scope=all          # Analyze both user and project

Output Interpretation

• Token savings: Approximate reduction in context window usage per session
• Storage savings: Actual disk space recoverable
• Risk level: How likely the change is to affect functionality
• Benefit ratio: Savings vs effort to implement

When presenting findings, always show the comparative benefit so users can make informed decisions about which optimizations to pursue.

Usage: /housekeeping # Analyze ~/.claude (default) /housekeeping scope=project # Analyze .claude in current project /housekeeping scope=all # Analyze both

What it does: 1. Discovery - Scans hooks, commands, plugins, storage, configs, rules, agents 2. Analysis - Calculates token cost, storage impact, value, risk rating (SAFE/LOW/MEDIUM/HIGH) 3. Action Plan - Generates prioritized report with before/after comparisons 4. Interactive Execution - User picks actions, backups created before changes

EXAMPLE OUTPUT

Claude Housekeeping Report

  Scope: user (~/.claude)
  Analyzed: 2026-01-12
  Total Storage: ~2.8GB

  ---
  Executive Summary
  ┌─────────────────────────┬────────────────────────────────┬───────────────────────────┐
  │         Metric          │            Current             │     Potential Savings     │
  ├─────────────────────────┼────────────────────────────────┼───────────────────────────┤
  │ Storage                 │ 2.8 GB                         │ ~2.3 GB recoverable (82%) │
  ├─────────────────────────┼────────────────────────────────┼───────────────────────────┤
  │ CLAUDE.md size          │ 37KB (~9k tokens)              │ Could trim 50%+           │
  ├─────────────────────────┼────────────────────────────────┼───────────────────────────┤
  │ Transcript files        │ 2,470 files / 392MB            │ Archive older sessions    │
  ├─────────────────────────┼────────────────────────────────┼───────────────────────────┤
  │ Plugin cache duplicates │ 5 temp_git dirs + old versions │ ~2MB recoverable          │
  ├─────────────────────────┼────────────────────────────────┼───────────────────────────┤
  │ Orphaned hooks          │ 16 hooks not in settings       │ Not loading, but clutter  │
  └─────────────────────────┴────────────────────────────────┴───────────────────────────┘
  ---
  🔴 High Priority (Largest Impact)
  ┌─────┬───────────────────────┬──────────────────────┬───────────────────────────────────┬────────┐
  │  #  │         Item          │         Size         │              Action               │  Risk  │
  ├─────┼───────────────────────┼──────────────────────┼───────────────────────────────────┼────────┤
  │ 1   │ projects/             │ 1.8 GB               │ Archive/delete old project caches │ MEDIUM │
  ├─────┼───────────────────────┼──────────────────────┼───────────────────────────────────┼────────┤
  │ 2   │ transcripts/          │ 392 MB (2,470 files) │ Archive transcripts > 30 days     │ LOW    │
  ├─────┼───────────────────────┼──────────────────────┼───────────────────────────────────┼────────┤
  │ 3   │ file-history/         │ 167 MB               │ Purge old file history            │ LOW    │
  ├─────┼───────────────────────┼──────────────────────┼───────────────────────────────────┼────────┤
  │ 4   │ debug/                │ 86 MB                │ Clear debug logs                  │ SAFE   │
  ├─────┼───────────────────────┼──────────────────────┼───────────────────────────────────┼────────┤
  │ 5   │ hook-logs/Archive.zip │ 29 MB                │ Delete archived logs              │ SAFE   │
  ├─────┼───────────────────────┼──────────────────────┼───────────────────────────────────┼────────┤
  │ 6   │ telemetry/            │ 27 MB                │ Clear telemetry data              │ SAFE   │
  ├─────┼───────────────────────┼──────────────────────┼───────────────────────────────────┼────────┤
  │ 7   │ history.jsonl         │ 12 MB                │ Truncate/rotate                   │ LOW    │
  └─────┴───────────────────────┴──────────────────────┴───────────────────────────────────┴────────┘
  ---
  🟡 Medium Priority (Optimization)
  ┌─────┬────────────────────────────────┬──────────────────────────────┬─────────────────────────────────┬──────────────────────────┐
  │  #  │              Item              │           Current            │             Action              │         Benefit          │
  ├─────┼────────────────────────────────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────┤
  │ 8   │ CLAUDE.md                      │ 37KB / 954 lines             │ Trim redundant lessons/patterns │ ~5k tokens/session saved │
  ├─────┼────────────────────────────────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────┤
  │ 9   │ shell-snapshots/               │ 7.6 MB                       │ Delete old snapshots            │ Storage cleanup          │
  ├─────┼────────────────────────────────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────┤
  │ 10  │ task-logs/                     │ 6.2 MB                       │ Archive old task logs           │ Storage cleanup          │
  ├─────┼────────────────────────────────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────┤
  │ 11  │ todos/                         │ 5.1 MB                       │ Purge completed old todos       │ Storage cleanup          │
  ├─────┼────────────────────────────────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────┤
  │ 12  │ Plugin cache: temp_git_*       │ 5 dirs / ~1 MB               │ Delete orphaned temp dirs       │ Cleaner cache            │
  ├─────┼────────────────────────────────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────┤
  │ 13  │ Plugin cache: old versions     │ compound-eng 2.9.3 vs 2.23.1 │ Remove old version              │ ~1 MB                    │
  ├─────┼────────────────────────────────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────┤
  │ 14  │ security_warnings_state_*.json │ 5 files                      │ Clean up state files            │ Minor clutter            │
  └─────┴────────────────────────────────┴──────────────────────────────┴─────────────────────────────────┴──────────────────────────┘
  ---
  🟢 Low Priority (Nice to Have)
  ┌─────┬──────────────────────────────┬─────────────────────────────────┬──────────────────────────────────┐
  │  #  │             Item             │              Issue              │              Action              │
  ├─────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────────────┤
  │ 15  │ Orphaned hooks (16 files)    │ Not configured in settings.json │ Archive or delete unused         │
  ├─────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────────────┤
  │ 16  │ node_modules/                │ 81 MB                           │ Required for hooks - leave       │
  ├─────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────────────┤
  │ 17  │ Root shell scripts (6 files) │ Utility scripts                 │ Review if needed                 │
  ├─────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────────────┤
  │ 18  │ statsig/                     │ 1.2 MB                          │ Analytics cache - optional clear │
  ├─────┼──────────────────────────────┼─────────────────────────────────┼──────────────────────────────────┤
  │ 19  │ Disabled plugins (27)        │ Cached but disabled             │ Could uninstall                  │
  └─────┴──────────────────────────────┴─────────────────────────────────┴──────────────────────────────────┘
  ---
  Detailed Findings

  Hooks Analysis (28 found, 2 configured)

  Configured in settings.json:
  - PreCompact → bd prime
  - SessionStart → bd prime

  Orphaned hook files (not in settings, not loading):
  ┌──────────────────────────┬────────┬─────────────────────────────┐
  │           File           │  Size  │           Status            │
  ├──────────────────────────┼────────┼─────────────────────────────┤
  │ default.js               │ 8.7 KB │ Complex framework, NOT USED │
  ├──────────────────────────┼────────┼─────────────────────────────┤
  │ enhanced-hook.js         │ 17 KB  │ NOT USED                    │
  ├──────────────────────────┼────────┼─────────────────────────────┤
  │ hook-manager.js          │ 13 KB  │ NOT USED                    │
  ├──────────────────────────┼────────┼─────────────────────────────┤
  │ claude-logger.js         │ 12 KB  │ NOT USED                    │
  ├──────────────────────────┼────────┼─────────────────────────────┤
  │ log-monitor.js           │ 10 KB  │ NOT USED                    │
  ├──────────────────────────┼────────┼─────────────────────────────┤
  │ session-start.js         │ 10 KB  │ NOT USED                    │
  ├──────────────────────────┼────────┼─────────────────────────────┤
  │ universal-interceptor.js │ 6.8 KB │ NOT USED                    │
  ├──────────────────────────┼────────┼─────────────────────────────┤
  │ + 9 more files           │ ~25 KB │ NOT USED                    │
  └──────────────────────────┴────────┴─────────────────────────────┘
  Assessment: These hooks exist but aren't wired up in settings.json. They're dead weight.

  Commands Analysis (34 found)

  All 34 command files in ~/.claude/commands/ consuming 180KB. Most appear actively used.

  Plugins Analysis

  Enabled plugins: 14
  Disabled plugins: 27 (still cached)

  Cache issues:
  - 5 orphaned temp_git_* directories (~1 MB)
  - Duplicate compound-engineering versions (2.9.3 AND 2.23.1)
  - 38 cached official plugins (many disabled)

  Storage Breakdown
  ┌───────────────┬────────┬────────────────┬──────────────────────┐
  │   Directory   │  Size  │      Type      │    Recommendation    │
  ├───────────────┼────────┼────────────────┼──────────────────────┤
  │ projects/     │ 1.8 GB │ Project caches │ Archive old projects │
  ├───────────────┼────────┼────────────────┼──────────────────────┤
  │ transcripts/  │ 392 MB │ Session logs   │ Archive > 30 days    │
  ├───────────────┼────────┼────────────────┼──────────────────────┤
  │ file-history/ │ 167 MB │ Edit history   │ Purge > 7 days       │
  ├───────────────┼────────┼────────────────┼──────────────────────┤
  │ debug/        │ 86 MB  │ Debug logs     │ Clear all            │
  ├───────────────┼────────┼────────────────┼──────────────────────┤
  │ node_modules/ │ 81 MB  │ Dependencies   │ Keep (required)      │
  ├───────────────┼────────┼────────────────┼──────────────────────┤
  │ plugins/      │ 38 MB  │ Plugin cache   │ Clean duplicates     │
  ├───────────────┼────────┼────────────────┼──────────────────────┤
  │ hook-logs/    │ 29 MB  │ Hook logs      │ Delete archive.zip   │
  ├───────────────┼────────┼────────────────┼──────────────────────┤
  │ telemetry/    │ 27 MB  │ Usage data     │ Clear                │
  └───────────────┴────────┴────────────────┴──────────────────────┘
  ---
  Before/After Comparison
  ┌───────────────────┬────────┬────────────────────────┬─────────────┐
  │      Metric       │ Before │ After (if all actions) │ Improvement │
  ├───────────────────┼────────┼────────────────────────┼─────────────┤
  │ Total storage     │ 2.8 GB │ ~500 MB                │ -82%        │
  ├───────────────────┼────────┼────────────────────────┼─────────────┤
  │ Transcript files  │ 2,470  │ ~100                   │ -96%        │
  ├───────────────────┼────────┼────────────────────────┼─────────────┤
  │ CLAUDE.md tokens  │ ~9k    │ ~4k                    │ -55%        │
  ├───────────────────┼────────┼────────────────────────┼─────────────┤
  │ Plugin cache dirs │ 16     │ 11                     │ -31%        │
  ├───────────────────┼────────┼────────────────────────┼─────────────┤
  │ Hook files        │ 28     │ 4                      │ -86%        │
  └───────────────────┴────────┴────────────────────────┴─────────────┘
  ---
  Recommended Actions

  Select which to perform by number:

  Storage Recovery (High Impact):
  1. Archive projects/ directories older than 60 days → ~1.5 GB
  2. Archive transcripts/ older than 30 days → ~350 MB
  3. Clear file-history/ older than 7 days → ~150 MB
  4. Delete debug/ contents → 86 MB
  5. Delete hook-logs/Archive.zip → 29 MB
  6. Clear telemetry/ → 27 MB
  7. Truncate history.jsonl to last 1000 entries → ~10 MB

  Plugin Cleanup:
  8. [ ] Delete 5 temp_git_* directories → ~1 MB
  9. [ ] Remove old compound-engineering 2.9.3 → ~1 MB
  10. [ ] Uninstall disabled plugins (27) → ~5 MB cache

  Hook Cleanup:
  11. [ ] Archive 16 orphaned hook files → ~100 KB + cleaner dir
  12. [ ] Delete sample hooks in claude-hooks/ → ~10 KB

  Config Optimization:
  13. [ ] Trim CLAUDE.md redundant sections → ~5k tokens/session
  14. [ ] Remove 5 security_warnings_state_*.json files → cleanup
  15. [ ] Review/delete root .sh scripts if unused → cleanup

  ---

⏺ ---
  Which actions would you like me to perform?

  Options:
  - "all" - Execute all safe actions (will confirm MEDIUM risk items)
  - "1-7" - Storage recovery only
  - "8-10" - Plugin cleanup only
  - "11-12" - Hook cleanup only
  - "13-15" - Config optimization only
  - Specific numbers - e.g., "1, 4, 5, 8"

  I'll create backups before any MEDIUM+ risk operations.

LICENSE

MIT