addxai Batch Project Cache Cleanup (Clean Cache)
Description
When developing multiple Flutter/Android/iOS projects, build artifacts and dependency caches grow rapidly. This Skill batch-scans the workspace, performs tiered cleanup by safety level, and frees disk space while preserving global dependency caches to avoid re-downloading on the next build.
Rules
Rule 0 — Safety Tiers (Core Principle)
Cleanup is divided into three tiers. Only L1 is executed by default; L2/L3 require explicit user confirmation:
| Tier | What Gets Deleted | Rebuild Cost | Estimated Space Freed |
|---|---|---|---|
| L1 Safe Cleanup | Build artifacts (build/, DerivedData, .dart_tool/, bazel-*) + stale dev tool caches (Homebrew old version packages, Bazel global cache) | Recompile only, no network cost | Large |
| L2 Dependency Cleanup | Project-level dependencies (Pods/, node_modules/, .gradle/caches/) | Requires pod install / npm install / gradle sync, but recovers from global cache, relatively fast |
Medium |
| L3 Deep Cleanup | Global caches (~/.gradle/caches/, CocoaPods repo index, Pub global cache) | All projects need to re-download on first build, very slow | Small |
Key distinction: L2 deletes project-internal Pods/, node_modules/, but global caches remain (~/.cocoapods/repos/, npm cache, ~/.gradle/caches/), so re-installing will mostly recover packages from local cache without re-downloading.
Rule 1 — Step 1: Scan Workspace
Accept the user-specified workspace root directory (default ~/Desktop or the parent of the current directory) and scan all cleanable cache directories:
# Scan script — find all cache directories and their sizes
WORKSPACE="${1:-.}"
echo "=== L1 Build Artifacts (safe to delete, just recompile) ==="
# Flutter build artifacts
find "$WORKSPACE" -name ".dart_tool" -type d -maxdepth 6 2>/dev/null | while read d; do du -sh "$d"; done
# Android build artifacts
find "$WORKSPACE" -path "*/app/build" -type d -maxdepth 6 2>/dev/null | while read d; do du -sh "$d"; done
find "$WORKSPACE" -name "build" -path "*android*" -type d -maxdepth 6 2>/dev/null | while read d; do du -sh "$d"; done
# iOS DerivedData (global)
du -sh ~/Library/Developer/Xcode/DerivedData/ 2>/dev/null
# Bazel artifacts
find "$WORKSPACE" -name "bazel-*" -type l -maxdepth 4 2>/dev/null | while read d; do echo "$d (symlink)"; done
# Homebrew old version packages cache
du -sh ~/Library/Caches/Homebrew/ 2>/dev/null
# Bazel global cache
du -sh ~/Library/Caches/bazel/ 2>/dev/null
du -sh ~/Library/Caches/bazelisk/ 2>/dev/null
echo ""
echo "=== L2 Project-Level Dependencies (need install after deletion, but recover from global cache) ==="
# iOS Pods
find "$WORKSPACE" -name "Pods" -type d -maxdepth 5 2>/dev/null | while read d; do du -sh "$d"; done
# Node modules
find "$WORKSPACE" -name "node_modules" -type d -maxdepth 5 -prune 2>/dev/null | while read d; do du -sh "$d"; done
# Android .gradle (project-level)
find "$WORKSPACE" -name ".gradle" -type d -maxdepth 4 2>/dev/null | while read d; do du -sh "$d"; done
# Flutter .flutter-plugins
find "$WORKSPACE" -name ".flutter-plugins" -type f -maxdepth 5 2>/dev/null
find "$WORKSPACE" -name ".flutter-plugins-dependencies" -type f -maxdepth 5 2>/dev/null
echo ""
echo "=== L3 Global Caches (all projects must re-download after deletion, use caution) ==="
du -sh ~/.gradle/caches/ 2>/dev/null
du -sh ~/.cocoapods/repos/ 2>/dev/null
du -sh ~/.pub-cache/ 2>/dev/null
du -sh ~/Library/Caches/CocoaPods/ 2>/dev/null
npm cache ls 2>/dev/null | wc -l | xargs -I{} echo "npm cache: {} entries"
Output format — summary table grouped by project:
## Cache Scan Report
| Project | Type | L1 Build Artifacts | L2 Project Dependencies | Total |
|------|------|-----------|-----------|------|
| app-ios | iOS | 0M | 288M (Pods) | 288M |
| app-android | Android | 450M (build) | 156M (.gradle) | 606M |
| app-flutter-module | Flutter | 36M (.dart_tool) | — | 36M |
| ... | | | | |
### Global Caches
| Cache | Size |
|------|------|
| DerivedData | 3.2G |
| ~/.gradle/caches | 1.1G |
| ~/.cocoapods/repos | 800M |
**L1 freeable: X.X GB** | L2 freeable: X.X GB | L3 freeable: X.X GB
**Total: X.X GB**
Rule 2 — Step 2: User Confirmation of Cleanup Level
After displaying the scan report, ask the user:
Recommended: L1 (safe cleanup), estimated X.X GB freed. Next build only requires recompilation, no re-downloads.
Also run L2? L2 will delete Pods/node_modules/.gradle, but global caches remain;
re-installing will mostly recover from local cache (typically < 2 minutes).
Choose: L1 / L1+L2 / L1+L2+L3 (not recommended)
L2 or L3 must not be executed without confirmation.
Rule 3 — Step 3: Execute Cleanup
Execute the corresponding tier based on user selection. Print the path and size before each rm so the user can see what is being deleted.
L1 Cleanup Commands
# Flutter build artifacts
find "$WORKSPACE" -name ".dart_tool" -type d -maxdepth 6 -exec rm -rf {} + 2>/dev/null
# Android build directories (only delete app/build and module build, not source directories)
find "$WORKSPACE" -path "*/app/build" -type d -maxdepth 6 -exec rm -rf {} + 2>/dev/null
# iOS DerivedData (shared by all projects, cleaned at once)
rm -rf ~/Library/Developer/Xcode/DerivedData/*
# Bazel output (only delete content pointed to by symlinks)
# bazel clean must be executed in the project directory
find "$WORKSPACE" -name "WORKSPACE" -o -name "MODULE.bazel" -maxdepth 4 2>/dev/null | \
xargs -I{} dirname {} | sort -u | while read proj; do
echo "Cleaning bazel in $proj"
(cd "$proj" && bazel clean 2>/dev/null)
done
# Homebrew old version packages (only deletes expired downloads, does not affect installed software)
brew cleanup 2>/dev/null
# Bazel global cache (compilation intermediates, just recompile after deletion)
rm -rf ~/Library/Caches/bazel/ ~/Library/Caches/bazelisk/
L2 Cleanup Commands
# iOS Pods (preserves Podfile.lock; next pod install will restore consistent versions)
find "$WORKSPACE" -name "Pods" -type d -maxdepth 5 -exec rm -rf {} + 2>/dev/null
# Node modules (preserves package-lock.json)
find "$WORKSPACE" -name "node_modules" -type d -maxdepth 5 -prune -exec rm -rf {} + 2>/dev/null
# Android .gradle project cache
find "$WORKSPACE" -name ".gradle" -type d -maxdepth 4 -exec rm -rf {} + 2>/dev/null
# Flutter generated files
find "$WORKSPACE" -name ".flutter-plugins" -type f -maxdepth 5 -delete 2>/dev/null
find "$WORKSPACE" -name ".flutter-plugins-dependencies" -type f -maxdepth 5 -delete 2>/dev/null
L3 Cleanup Commands (require secondary confirmation)
echo "L3 will clear global caches — all projects will need to re-download dependencies on next build"
echo "Type YES to confirm"
# Gradle global cache
rm -rf ~/.gradle/caches/
# CocoaPods cache
pod cache clean --all
rm -rf ~/Library/Caches/CocoaPods/
# Pub global cache
flutter pub cache clean
# npm cache
npm cache clean --force
Rule 4 — Step 4: Verify and Report
# Re-scan after cleanup and compare freed space
echo "=== Cleanup Complete ==="
echo "Space freed: X.X GB"
echo ""
echo "Recovery guide for next build:"
echo " Flutter: flutter pub get"
echo " iOS: cd <project> && pod install"
echo " Android: Open project, Gradle syncs automatically"
echo " Node.js: npm install"
Rule 5 — What Must Not Be Deleted (Red Lines)
| Never Delete | Reason |
|---|---|
Podfile.lock / package-lock.json / pubspec.lock |
Lock files ensure version consistency; deleting them could introduce dependency version changes |
.gradle/wrapper/ |
Gradle wrapper jar; deleting it breaks the gradle command itself |
~/.pub-cache/ (at L1/L2) |
Flutter global package cache; deleting it forces all projects to re-download |
~/.gradle/caches/ (at L1/L2) |
Gradle global dependency cache |
~/.cocoapods/repos/ (at L1/L2) |
CocoaPods spec repo index |
Any src/ or source files |
Only delete build artifacts and caches, never touch source code |
.git/ |
git repository data |
Rule 6 — Quick Single-Project Cleanup
If the user only wants to clean a single project rather than batch scanning:
# Flutter project
cd <project> && flutter clean && flutter pub get
# iOS project
cd <project>/ios && rm -rf Pods/ build/ && pod install
# Android project
cd <project>/android && ./gradlew clean
# Clean all DerivedData (affects all Xcode projects)
rm -rf ~/Library/Developer/Xcode/DerivedData/*
Examples
Bad
User: "clean up the caches"
AI: Directly executes rm -rf ~/.gradle/caches/ ~/.cocoapods/repos/ ~/.pub-cache/
→ Deleted global caches; all projects will spend 30 minutes re-downloading on next build
User: "disk space is low"
AI: Only cleaned the build/ of one project in the current directory
→ The caches of 10 other projects remain; space freed is negligible
Good
User: "clean up the caches"
AI: Scans entire workspace → reports 8 projects with 4.2GB of caches →
recommends L1 to free 2.8GB (pure build artifacts) → user confirms →
executes cleanup → reports 2.8GB actually freed; next compile auto-recovers
User: "disk is almost full, free as much as possible"
AI: Scan report L1=2.8GB, L2=1.4GB → recommends L1+L2 →
explains L2 recovery method (pod install / npm install, recovers from global cache in ~1-2 minutes) →
user confirms L1+L2 → executes → frees 4.2GB