User Config: Storage

Analyze the Claude Code storage directory (~/.claude/) to identify bloat, session accumulation, and provide cleanup recommendations.

Related Skill: Invoke the user-config-management skill for comprehensive user configuration guidance.

Usage

/user-config:storage
/user-config:storage --verbose

Arguments

• --verbose - Show detailed file listings in addition to summary

Workflow

Step 1: Comprehensive Storage Analysis

Analyze ALL folders in ~/.claude/:

echo "Claude Code Storage Analysis"
echo "============================"
echo ""

# Total size
TOTAL=$(du -sh ~/.claude 2>/dev/null | cut -f1)
echo "Total: $TOTAL"
echo ""

# By category - ALL folders
echo "By Category:"
echo "------------"
for dir in projects debug plugins file-history plans shell-snapshots todos statsig local; do
  if [ -d "$HOME/.claude/$dir" ]; then
    SIZE=$(du -sh "$HOME/.claude/$dir" 2>/dev/null | cut -f1)
    COUNT=$(find "$HOME/.claude/$dir" -type f 2>/dev/null | wc -l)
    printf "  %-16s %8s  (%d files)\n" "$dir/" "$SIZE" "$COUNT"
  fi
done

# Individual files
for file in history.jsonl settings.json settings.local.json CLAUDE.md; do
  if [ -f "$HOME/.claude/$file" ]; then
    SIZE=$(du -sh "$HOME/.claude/$file" 2>/dev/null | cut -f1)
    printf "  %-16s %8s\n" "$file" "$SIZE"
  fi
done

Step 2: Project Breakdown (Top 5)

echo ""
echo "Projects (top 5 by size):"
echo "-------------------------"
du -sh ~/.claude/projects/*/ 2>/dev/null | sort -rh | head -5 | while read size path; do
  name=$(basename "$path")
  # Truncate long names
  if [ ${#name} -gt 40 ]; then
    name="${name:0:37}..."
  fi
  printf "  %-42s %8s\n" "$name" "$size"
done

Step 3: Current Project Analysis

For the current project, analyze session and agent files:

# Cross-platform project path detection
if [ -n "$MSYSTEM" ]; then
  # Git Bash on Windows
  PROJECT_DIR="$HOME/.claude/projects/$(pwd | sed 's|^/\([a-z]\)/|\U\1--|' | sed 's|/|--|g')"
else
  # Unix-like
  PROJECT_DIR="$HOME/.claude/projects/$(pwd | sed 's/[\/:]/-/g' | sed 's/^-//')"
fi

echo ""
echo "Current Project Session Files:"
echo "------------------------------"
if [ -d "$PROJECT_DIR" ]; then
  TOTAL_FILES=$(find "$PROJECT_DIR" -maxdepth 1 -name "*.jsonl" 2>/dev/null | wc -l)
  AGENT_FILES=$(find "$PROJECT_DIR" -maxdepth 1 -name "agent-*.jsonl" 2>/dev/null | wc -l)
  SESSION_FILES=$((TOTAL_FILES - AGENT_FILES))

  echo "  Total .jsonl files: $TOTAL_FILES"
  echo "  Session files:      $SESSION_FILES"
  echo "  Agent transcripts:  $AGENT_FILES"
  echo ""
  echo "  By Age:"
  echo "    Today:     $(find "$PROJECT_DIR" -maxdepth 1 -name "*.jsonl" -mtime 0 2>/dev/null | wc -l)"
  echo "    1-3 days:  $(find "$PROJECT_DIR" -maxdepth 1 -name "*.jsonl" -mtime +0 -mtime -3 2>/dev/null | wc -l)"
  echo "    3-7 days:  $(find "$PROJECT_DIR" -maxdepth 1 -name "*.jsonl" -mtime +2 -mtime -7 2>/dev/null | wc -l)"
  echo "    >7 days:   $(find "$PROJECT_DIR" -maxdepth 1 -name "*.jsonl" -mtime +7 2>/dev/null | wc -l)"
else
  echo "  No session data found for current project"
fi

Step 4: Debug Folder Analysis

The debug/ folder contains transcript files for debugging Claude Code itself:

echo ""
echo "Debug Transcripts:"
echo "------------------"
if [ -d "$HOME/.claude/debug" ]; then
  DEBUG_SIZE=$(du -sh "$HOME/.claude/debug" 2>/dev/null | cut -f1)
  DEBUG_COUNT=$(find "$HOME/.claude/debug" -type f 2>/dev/null | wc -l)
  OLD_DEBUG=$(find "$HOME/.claude/debug" -type f -mtime +7 2>/dev/null | wc -l)
  OLD_DEBUG_SIZE=$(find "$HOME/.claude/debug" -type f -mtime +7 -exec du -ch {} + 2>/dev/null | tail -1 | cut -f1)

  echo "  Total: $DEBUG_SIZE ($DEBUG_COUNT files)"
  echo "  >7 days old: $OLD_DEBUG files ($OLD_DEBUG_SIZE)"
else
  echo "  No debug folder found"
fi

Step 5: Large Files Detection

Find unusually large files that may indicate bloat:

echo ""
echo "Large Files (>10MB):"
echo "--------------------"
LARGE_FILES=$(find ~/.claude -type f -size +10M 2>/dev/null)
if [ -n "$LARGE_FILES" ]; then
  find ~/.claude -type f -size +10M -exec ls -lh {} \; 2>/dev/null | awk '{print "  " $5 "  " $9}' | head -10
else
  echo "  None found"
fi

Step 6: Reclaimable Space Summary

echo ""
echo "Reclaimable Space:"
echo "------------------"

# Sessions >7 days
if [ -d "$PROJECT_DIR" ]; then
  OLD_SESSIONS=$(find "$PROJECT_DIR" -maxdepth 1 -name "*.jsonl" ! -name "agent-*" -mtime +7 -exec du -ch {} + 2>/dev/null | tail -1 | cut -f1)
  OLD_AGENTS=$(find "$PROJECT_DIR" -maxdepth 1 -name "agent-*.jsonl" -mtime +7 -exec du -ch {} + 2>/dev/null | tail -1 | cut -f1)
  echo "  Sessions >7 days:  ${OLD_SESSIONS:-0}"
  echo "  Agents >7 days:    ${OLD_AGENTS:-0}"
fi

# Debug >7 days
if [ -d "$HOME/.claude/debug" ]; then
  OLD_DEBUG_SIZE=$(find "$HOME/.claude/debug" -type f -mtime +7 -exec du -ch {} + 2>/dev/null | tail -1 | cut -f1)
  echo "  Debug >7 days:     ${OLD_DEBUG_SIZE:-0}"
fi

# Statsig (always safe)
if [ -d "$HOME/.claude/statsig" ]; then
  STATSIG_SIZE=$(du -sh "$HOME/.claude/statsig" 2>/dev/null | cut -f1)
  echo "  Statsig cache:     $STATSIG_SIZE (always safe to clear)"
fi

Step 7: Generate Recommendations

Based on analysis, provide actionable recommendations:

Recommendations:
----------------

Thresholds:

Condition	Severity	Recommendation
Total > 1GB	CRITICAL	Run /user-config:prune --include-debug
Total > 500MB	WARNING	Run /user-config:prune 7
Agent files > 1000	WARNING	Run /user-config:cleanup-agents 7
Debug > 100MB	WARNING	Run /user-config:cleanup-debug 7
Files >7 days exist	TIP	Run /user-config:cleanup-sessions 7 --dry-run

Step 8: Quick Commands Summary

Always show available cleanup commands:

Quick Commands:
---------------
/user-config:cleanup-sessions 7     - Remove session files >7 days old
/user-config:cleanup-agents 7       - Remove agent transcripts >7 days old
/user-config:cleanup-debug 7        - Remove debug transcripts >7 days old
/user-config:prune 7                - Comprehensive cleanup (sessions + agents + statsig)
/user-config:prune --include-debug  - Full cleanup including debug folder

Folder Reference

Folder	Contents	Safe to Clean
projects/	Session and agent transcripts per project	Yes (old files)
debug/	Debug transcripts for troubleshooting	Yes (old files)
plugins/	Installed plugin cache	Only via reinstall
file-history/	File edit history for undo	Careful - loses undo
plans/	Saved execution plans	Yes (old files)
shell-snapshots/	Shell state snapshots	Yes
todos/	Todo list state	Yes (old files)
statsig/	Analytics cache	Always safe
history.jsonl	Command history	Usually keep
settings.json	User settings	Never clean
CLAUDE.md	User instructions	Never clean

Notes

• Storage analysis is read-only and makes no changes
• Use specific cleanup commands to actually free space
• For full diagnostics including API status, use /diagnose-performance
• Plugin cache can only be cleaned by reinstalling plugins