User Config: Cleanup Debug

Remove old debug transcript files from Claude Code's debug directory. Debug files store execution traces for troubleshooting and can accumulate significantly.

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

Usage

/user-config:cleanup-debug                     # Default: 7 days
/user-config:cleanup-debug 3                   # Remove debug files older than 3 days
/user-config:cleanup-debug --dry-run           # Preview what would be deleted
/user-config:cleanup-debug 0                   # Remove ALL debug files (nuclear)

Arguments

Argument	Description	Default
[days]	Remove debug files older than N days (must be non-negative integer)	7
--dry-run	Preview without deleting	false

Safety Features

• Dry-run available: Always preview before deleting
• Confirmation required: Claude MUST use AskUserQuestion tool before any deletion
• Preserves recent files: Never deletes today's debug files
• Input validation: DAYS must be a non-negative integer

What Are Debug Files?

The ~/.claude/debug/ folder contains transcript files generated when Claude Code encounters issues or when debug mode is enabled. These files help Anthropic diagnose problems but are not needed for normal operation.

Characteristics:

• Location: ~/.claude/debug/
• File types: .jsonl transcripts, crash logs, trace files
• Growth rate: Varies with usage; can grow 50-100 MB/week in heavy usage
• Safe to delete: Yes, completely safe

Workflow

Step 1: Parse and Validate Arguments

DAYS = first numeric argument OR 7
DRY_RUN = true if --dry-run present

# VALIDATION: Ensure DAYS is a non-negative integer
if DAYS is not a valid non-negative integer:
  Report error: "Error: days must be a non-negative integer (got: {value})"
  Exit without action

DEBUG_DIR="$HOME/.claude/debug"

Step 2: Analyze Debug Directory

echo "Debug Cleanup"
echo "============="
echo ""

if [ ! -d "$DEBUG_DIR" ]; then
  echo "No debug directory found at $DEBUG_DIR"
  exit 0
fi

# Current size
TOTAL_SIZE=$(du -sh "$DEBUG_DIR" 2>/dev/null | cut -f1)
TOTAL_COUNT=$(find "$DEBUG_DIR" -type f 2>/dev/null | wc -l)

echo "Debug directory: $DEBUG_DIR"
echo "Total size: $TOTAL_SIZE ($TOTAL_COUNT files)"
echo ""

# Files to remove
if [ "$DAYS" -eq 0 ]; then
  # Remove all
  FILES_TO_REMOVE=$(find "$DEBUG_DIR" -type f 2>/dev/null)
  REMOVE_COUNT=$TOTAL_COUNT
  REMOVE_SIZE=$TOTAL_SIZE
else
  # Remove older than N days
  FILES_TO_REMOVE=$(find "$DEBUG_DIR" -type f -mtime +$DAYS 2>/dev/null)
  REMOVE_COUNT=$(echo "$FILES_TO_REMOVE" | grep -c . 2>/dev/null || echo 0)
  REMOVE_SIZE=$(find "$DEBUG_DIR" -type f -mtime +$DAYS -exec du -ch {} + 2>/dev/null | tail -1 | cut -f1)
fi

echo "Files older than $DAYS days: $REMOVE_COUNT"
echo "Space to free: ${REMOVE_SIZE:-0}"

Step 3: Show Age Breakdown

echo ""
echo "Age Breakdown:"
echo "  Today:     $(find "$DEBUG_DIR" -type f -mtime 0 2>/dev/null | wc -l) files"
echo "  1-3 days:  $(find "$DEBUG_DIR" -type f -mtime +0 -mtime -3 2>/dev/null | wc -l) files"
echo "  3-7 days:  $(find "$DEBUG_DIR" -type f -mtime +2 -mtime -7 2>/dev/null | wc -l) files"
echo "  >7 days:   $(find "$DEBUG_DIR" -type f -mtime +7 2>/dev/null | wc -l) files"

Step 4: Preview or Delete

Dry Run Mode:

echo ""
echo "[DRY RUN] Would remove $REMOVE_COUNT files (${REMOVE_SIZE:-0})"
echo ""
echo "To execute, run: /user-config:cleanup-debug $DAYS"

Execute (CONFIRMATION REQUIRED):

1. Show preview (same as dry run)
2. MANDATORY: Use AskUserQuestion tool to get explicit confirmation:
   Question: "Delete {count} debug files ({size})? This cannot be undone."
   Options: ["Yes, delete files", "No, cancel"]
3. If user confirms "Yes", execute:
   if [ "$DAYS" -eq 0 ]; then
     rm -rf "$DEBUG_DIR"/*
   else
     find "$DEBUG_DIR" -type f -mtime +$DAYS -delete
   fi
4. If user selects "No" or any other response, abort without deletion
5. Report results with before/after comparison

CRITICAL: Never delete files without explicit user confirmation via AskUserQuestion.

Step 5: Verification

After deletion, verify cleanup:

NEW_SIZE=$(du -sh "$DEBUG_DIR" 2>/dev/null | cut -f1)
NEW_COUNT=$(find "$DEBUG_DIR" -type f 2>/dev/null | wc -l)

echo ""
echo "Cleanup Complete!"
echo "================="
echo "Before: $TOTAL_SIZE ($TOTAL_COUNT files)"
echo "After:  ${NEW_SIZE:-0} ($NEW_COUNT files)"
echo "Freed:  ${REMOVE_SIZE:-0}"

Example Output

Dry Run

Debug Cleanup
=============

Debug directory: ~/.claude/debug
Total size: 359M (878 files)

Files older than 7 days: 0
Space to free: 0

Age Breakdown:
  Today:     245 files
  1-3 days:  412 files
  3-7 days:  221 files
  >7 days:   0 files

[DRY RUN] Would remove 0 files (0)

To execute, run: /user-config:cleanup-debug 7

Actual Cleanup

Debug Cleanup
=============

Debug directory: ~/.claude/debug
Total size: 359M (878 files)

Files older than 3 days: 633
Space to free: 285M

Age Breakdown:
  Today:     245 files
  1-3 days:  412 files
  3-7 days:  221 files
  >7 days:   0 files

[AskUserQuestion: "Delete 633 debug files (285M)? This cannot be undone."]
> User selected: "Yes, delete files"

Removing 633 debug files...

Cleanup Complete!
=================
Before: 359M (878 files)
After:  74M (245 files)
Freed:  285M

Cleanup Strategies

Goal	Command
Conservative	/user-config:cleanup-debug 7
Moderate	/user-config:cleanup-debug 3
Aggressive	/user-config:cleanup-debug 1
Nuclear (all)	/user-config:cleanup-debug 0
Preview	/user-config:cleanup-debug --dry-run

Notes

• Debug files are completely safe to delete - they're only for troubleshooting
• Unlike session files, debug files are not per-project - they're global
• Debug files are NOT included in /user-config:prune by default - use --include-debug
• For maximum cleanup including debug, use /user-config:prune --nuclear
• If you need to report a bug, keep recent debug files (last 24 hours)