User Config: Cleanup Sessions

Remove old session files from Claude Code's project cache to free disk space. By default, removes files older than 7 days from the current project only.

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

Usage

/user-config:cleanup-sessions                    # Default: 7 days, current project, with confirmation
/user-config:cleanup-sessions 14                 # Remove files older than 14 days
/user-config:cleanup-sessions --dry-run          # Preview what would be deleted
/user-config:cleanup-sessions 7 --all-projects   # Clean all projects
/user-config:cleanup-sessions 3 --dry-run        # Preview aggressive cleanup

Arguments

Argument	Description	Default
[days]	Remove sessions older than N days (must be non-negative integer)	7
--dry-run	Preview without deleting	false
--all-projects	Clean all projects, not just current	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 sessions
• Project scoped: Defaults to current project only
• Input validation: DAYS must be a non-negative integer

Workflow

Step 1: Parse and Validate Arguments

DAYS = first numeric argument OR 7
DRY_RUN = true if --dry-run present
ALL_PROJECTS = true if --all-projects 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

Step 2: Determine Target Directory

if ALL_PROJECTS; then
  TARGET_DIR="$HOME/.claude/projects"
else
  # Current project only
  PROJECT_PATH=$(pwd | sed 's/[\/:]/-/g' | sed 's/^-//')
  TARGET_DIR="$HOME/.claude/projects/$PROJECT_PATH"
fi

Step 3: Find Files to Delete

# Find session files older than specified days (excludes agent files for separate handling)
# Note: This finds ALL .jsonl files - both sessions and agents
FILES=$(find "$TARGET_DIR" -name "*.jsonl" -mtime +$DAYS 2>/dev/null)
COUNT=$(echo "$FILES" | grep -c . 2>/dev/null || echo 0)
SIZE=$(find "$TARGET_DIR" -name "*.jsonl" -mtime +$DAYS -exec du -ch {} + 2>/dev/null | tail -1 | cut -f1)

Step 4: Preview or Delete

Dry Run Mode:

Cleanup Preview (Dry Run)
=========================
Target: {target_dir}
Files older than: {days} days

Files to remove: {count}
Space to free: {size}

Sample files:
  {first 10 files with sizes}

To execute cleanup, run: /user-config:cleanup-sessions {days}

Execution Mode (CONFIRMATION REQUIRED):

1. Show preview (same as dry run)
2. MANDATORY: Use AskUserQuestion tool to get explicit confirmation:
   Question: "Delete {count} session files ({size})? This cannot be undone."
   Options: ["Yes, delete files", "No, cancel"]
3. If user confirms "Yes", execute:
   find "$TARGET_DIR" -name "*.jsonl" -mtime +$DAYS -delete
4. If user selects "No" or any other response, abort without deletion
5. Report results:
   "Deleted {count} files, freed {size}"

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

Step 5: Verification

After deletion, verify cleanup:

REMAINING=$(find "$TARGET_DIR" -name "*.jsonl" 2>/dev/null | wc -l)
REMAINING_SIZE=$(du -sh "$TARGET_DIR" 2>/dev/null | cut -f1)
echo "Remaining: $REMAINING files ($REMAINING_SIZE)"

Example Output

Dry Run

Cleanup Preview (Dry Run)
=========================
Target: ~/.claude/projects/D--repos-gh-melodic-claude-code-plugins
Files older than: 7 days

Files to remove: 821
Space to free: 650M

Sample files (oldest first):
  55e42424-f5b6-4a26-98d5-1bed9176bf50.jsonl    15M  (16 days old)
  9536ec25-aeef-44c7-b606-9e5276f210dc.jsonl    15M  (14 days old)
  336198a5-dfa4-4266-86dc-3d90158b8e30.jsonl    15M  (12 days old)
  ...

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

Execution

Cleanup Session Files
=====================
Target: ~/.claude/projects/D--repos-gh-melodic-claude-code-plugins
Files older than: 7 days

Files to remove: 821
Space to free: 650M

[AskUserQuestion: "Delete 821 session files (650M)? This cannot be undone."]
> User selected: "Yes, delete files"

Deleting files...
Deleted 821 files, freed 650M

Remaining: 245 files (295M)

Notes

• This command removes BOTH session files and agent transcript files by age
• For agent-only cleanup, use /user-config:cleanup-agents
• Files from today are never deleted regardless of settings
• Claude Code has a default 30-day auto-cleanup, but this command allows manual intervention
• Use /user-config:storage first to understand current usage