Comprehensive Claude Code cache cleanup - removes old sessions, agents, debug transcripts, and temporary files
Cleans Claude Code cache to free disk space by removing old sessions, agents, and debug files.
/plugin marketplace add melodic-software/claude-code-plugins/plugin install claude-code-observability@melodic-software[days] [--dry-run] [--all-projects] [--include-debug] [--include-todos] [--nuclear]Comprehensive cleanup of Claude Code's cache directory. This is the "nuclear option" for freeing maximum disk space.
Related Skill: Invoke the user-config-management skill for comprehensive user configuration guidance.
/user-config:prune # Default: 7 days, current project
/user-config:prune 3 # Aggressive: 3 days
/user-config:prune --dry-run # Preview all cleanups
/user-config:prune --all-projects # Clean all projects
/user-config:prune --include-debug # Also clean debug transcripts
/user-config:prune --include-todos # Also clean old todo files
/user-config:prune --nuclear # Maximum cleanup (0 days, all flags)
| Argument | Description | Default |
|---|---|---|
[days] | Remove files 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 |
--include-debug | Also clean debug/ folder | false |
--include-todos | Also clean old todo state files | false |
--nuclear | Maximum cleanup: 0 days + all flags (--include-debug, --include-todos, --all-projects) + stale locks | false |
| Category | Location | Files | Notes |
|---|---|---|---|
| Sessions | projects/*/ | *.jsonl (non-agent) | Conversation history |
| Agents | projects/*/ | agent-*.jsonl | Subagent transcripts |
| Statsig | statsig/ | All | Analytics cache (always safe) |
| Shell Snapshots | shell-snapshots/ | All | Shell state snapshots |
| Plans | plans/ | *.json older than N days | Saved execution plans |
| Category | Location | Files | Notes |
|---|---|---|---|
| Debug | debug/ | All older than N days | Debug transcripts |
| Category | Location | Files | Notes |
|---|---|---|---|
| Todos | todos/ | *.json older than N days | Todo list state |
Maximum cleanup mode: Sets DAYS=0 (all files regardless of age) and enables all flags: --include-debug --include-todos --all-projects
Additionally, --nuclear cleans the following system directories:
| Category | Location | Files | Notes |
|---|---|---|---|
| Stale Locks | ~/.local/state/claude/locks/ | All | Fixes "Another Claude process is currently running" errors blocking claude update (Issue #13599) |
| Category | Reason |
|---|---|
~/.claude/CLAUDE.md | User instructions |
~/.claude/settings.json | User settings |
~/.claude/settings.local.json | Local settings |
~/.claude/commands/ | User commands |
~/.claude/skills/ | User skills |
~/.claude/agents/ | User agents |
~/.claude/hooks/ | User hooks |
~/.claude/history.jsonl | Command history |
~/.claude/plugins/ | Installed plugins (use /plugin uninstall) |
~/.claude/file-history/ | Edit undo history (dangerous to clear) |
DAYS = first numeric argument OR 7
DRY_RUN = true if --dry-run present
ALL_PROJECTS = true if --all-projects present
INCLUDE_DEBUG = true if --include-debug present
INCLUDE_TODOS = true if --include-todos 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
# Handle --nuclear flag (MUST be processed AFTER days parsing to override)
if --nuclear present:
DAYS = 0 # Nuclear means ALL files regardless of age
INCLUDE_DEBUG = true
INCLUDE_TODOS = true
ALL_PROJECTS = true
CLEAN_LOCKS = true # Also clean stale lock files
Calculate file counts and sizes for each category (sessions, agents, statsig, shell snapshots, plans, debug if included, todos if included, locks if nuclear).
Dry Run Mode:
If --dry-run is specified, show what would be deleted and exit.
Execute (CONFIRMATION REQUIRED):
1. Show cleanup summary
2. MANDATORY: Use AskUserQuestion tool to get explicit confirmation:
Question: "Delete {total_count} files (~{total_size})? This cannot be undone."
Options: ["Yes, delete files", "No, cancel"]
3. If user confirms "Yes", proceed with cleanup
4. If user selects "No" or any other response, abort without deletion
CRITICAL: Never delete files without explicit user confirmation via AskUserQuestion.
After deletion, report new total size of ~/.claude directory.
Comprehensive Cache Cleanup (--nuclear)
=======================================
Files older than: 0 days (ALL files)
Scope: ALL projects
Cleanup Summary:
----------------
Sessions: 507 files (400M)
Agents: 1,847 files (245M)
Statsig: 34K (always cleaned)
Shell snapshots: 12 files (1.5M)
Plans: 3 files (48K)
Debug: 878 files (359M) [--include-debug]
Locks: 2 files (0K) [--nuclear only]
---
Estimated space freed: ~1GB
[AskUserQuestion: "Delete 3247 files (~1GB)? This cannot be undone."]
> User selected: "Yes, delete files"
Proceeding with cleanup...
Sessions cleaned
Agents cleaned
Statsig cleaned
Shell snapshots cleaned
Plans cleaned
Debug cleaned
Locks cleaned (fixes 'Another Claude process is currently running' errors)
Cleanup Complete!
=================
Before: 1.5G
After: 450M
Space freed: ~1GB
| Goal | Command |
|---|---|
| Quick cleanup | /user-config:prune 7 |
| Aggressive | /user-config:prune 3 |
| Preview only | /user-config:prune --dry-run |
| Include debug | /user-config:prune --include-debug |
| All projects | /user-config:prune --all-projects |
| Maximum cleanup | /user-config:prune --nuclear (0 days, all flags, stale locks) |
/user-config:cleanup-sessions, /user-config:cleanup-agents, or /user-config:cleanup-debughistory.jsonl) is preserved/plugin uninstall to cleanfile-history/) is intentionally NOT cleaned - losing it means losing undo capability~/.local/state/claude/locks/) are only cleaned with --nuclear - fixes claude update blocking issues (Issue #13599)