Quick Clean Operator

Clean up project artifacts, build outputs, caches, and temporary files with a single command, reclaiming disk space and ensuring a fresh build state.

When to Use This Command

Run this command when...

• Your build cache is stale and you need a completely clean slate for a fresh build
• You want to reclaim disk space by removing node_modules, dist, and cache directories
• You are troubleshooting build issues and suspect cached artifacts are the cause

Avoid this command when...

• You are in the middle of a build and need cached artifacts for incremental compilation
• You want to selectively clean only one specific type of artifact

Quick Start

Copy
# .claude/commands/quick-clean-operator.md
---
allowed-tools: ["Bash"]
---
Detect and remove build artifacts, caches, and temporary files.
Show space reclaimed. Never remove source files or .git directory.

Example usage:

/quick-clean-operator

Example output:

Scanning for artifacts...
  node_modules/     482 MB
  dist/              12 MB
  .next/             89 MB
  __pycache__/        3 MB
  .pytest_cache/      1 MB

Total reclaimable: 587 MB
Cleaning... done
Space reclaimed: 587 MB

Core Concepts

Concept	Description
Artifact detection	Scans for known build output and cache directory patterns
Safe deletion	Never removes .git, source files, or configuration files
Space reporting	Shows the size of each artifact before and after cleanup
Multi-language	Handles Node.js, Python, Go, Rust, and Java artifacts

Scan Project Root
       |
  +----+----+----+----+
  |    |    |    |    |
node_ dist .next __py  .cache
mods               cache
  |    |    |    |    |
  +----+----+----+----+
       |
  Calculate Size --> Delete --> Report

Configuration

Option	Default	Description
targets	auto	What to clean (deps, build, cache, all)
dry-run	false	Show what would be cleaned without actually deleting
keep-deps	false	Skip node_modules and virtualenvs
min-size	1MB	Only report artifacts above this threshold
recursive	true	Clean in subdirectories for monorepo workspaces

Best Practices

1. Run dry-run first -- preview what will be removed before deleting, especially in unfamiliar projects.
2. Clean before measuring -- disk space measurements are only meaningful after stale artifacts are removed.
3. Reinstall after cleaning deps -- if you remove node_modules, run npm install before attempting to build.
4. Add to CI teardown -- clean artifacts at the end of CI jobs to avoid polluting shared caches.
5. Use .gitignore as a guide -- if something is in .gitignore, it is generally safe to clean.

Common Issues

1. Build fails after cleaning -- you need to reinstall dependencies. Run npm install or pip install -r requirements.txt.
2. Lock files accidentally removed -- the command should never remove lock files. If it does, check the target configuration.
3. Monorepo partial clean -- in a monorepo, cleaning only the root may miss workspace-level artifacts. Enable recursive mode.