React Native Dev Cache Scan

Dev cache scan (scan & report)

A read-only audit of regenerable developer caches on a macOS RN/Expo + native toolchain machine. The goal is to tell the user where their disk space went and how risky each item is to delete — so a human can make informed choices. Deletion is deliberately out of scope here; this is the "look before you cut" step.

When to run

Run when the user is low on disk and wants to understand reclaimable space, or asks to "clean up" any of: Xcode/DerivedData, simulators, iOS DeviceSupport, Gradle, CocoaPods, Expo, Bun/npm caches, or stray node_modules. Always run a scan before recommending or performing any deletion.

How to run

The scan is a bundled script so the measurements are consistent every time.

bash scripts/scan.sh                    # global caches only (fast, predictable)
bash scripts/scan.sh --projects ~/dev   # also sweep a projects folder for build artifacts
bash scripts/scan.sh --json             # machine-readable output (for tooling)

• Default scans only fixed global cache locations — fast and side-effect-free.
• Pass --projects <dir> when the user wants the per-project sweep. It anchors on each node_modules, totals that project's reclaimable artifacts (node_modules + ios/Pods + android build dirs), and reports each project's last activity — git's last-commit date when the project is a repo, otherwise the newest source-file mtime (heavy dirs pruned so it stays fast). Projects untouched for 60+ days are tagged (stale). This walks the tree (up to 4 levels) and can be slow on large folders, which is why it is opt-in. Offer it when the global scan doesn't account for enough space, since stray node_modules across abandoned projects is often the largest hidden total — and the activity age is what tells you which are safe to wipe.

The script prints free disk space, a size-ranked table tagged by severity tier, the simulator runtime list, and reclaimable subtotals. It deletes nothing.

Severity tiers

The script classifies each item so the user understands the consequence of deleting it, not just the savings:

• SAFE — pure regenerable cache (Gradle, CocoaPods, Expo, Bun, npm, CoreSimulator caches). Delete freely; worst case is a slower next install.
• CAUTION — regenerates, but at a real cost or only via a targeted delete:
  • DerivedData — deleting forces a full clean rebuild of every Xcode project.
  • iOS DeviceSupport — rebuilt on next device connect. The scan breaks this down per iOS version and protects the version(s) of your real physical devices, detected via xcrun xctrace list devices (it counts both connected and paired-but-offline devices, since both are yours). Those are labeled PROTECT-device; older versions are prunable. If no physical device is found at all, it falls back to protecting the newest version (PROTECT-newest). The reclaimable-CAUTION subtotal excludes whatever is protected.
  • CoreSimulator Devices — holds each simulator's apps + data. The scan breaks this down per simulator with size, iOS version, installed-app count, and days since last boot (from each sim's lastBootedAt). Sims marked empty (no user apps) are safe to wipe; sims not booted in 90+ days are flagged as stale prune candidates even if they hold apps. The report also gives "empty reclaimable" and "stale reclaimable" subtotals, and prints each sim's UDID. Note: iPads usually appear here as simulators, not physical devices — the DeviceSupport guardrail only protects real hardware, so an iPad with no physical unit is correctly absent there.
• PROTECT — do not blind-delete:
  • Xcode Archives — needed for App Store distribution and symbolicating production crash reports.
  • The newest simulator runtime — flagged PROTECT-newest. It usually matches the OS being actively developed/profiled against. Older runtimes are labeled prunable (7–10 GB each).

Simulator deletion safety (critical)

If the scan ever feeds into a deletion step, two rules are non-negotiable — both come from a real incident where an active simulator with live app data was destroyed:

• Delete simulators by UDID, never by name. Simulator names repeat across runtimes (an iPhone 17 Pro exists on both iOS 26.0 and 26.4), and xcrun simctl delete "iPhone 17 Pro" deletes every match across all runtimes at once — including the active sim you meant to keep. Always use xcrun simctl delete <UDID>, which the scan prints for every sim.
• Deleting a runtime cascades. Removing an iOS runtime marks all of its simulators "unavailable"; a later xcrun simctl delete unavailable then wipes those (possibly active) sims. Never chain those two operations blindly.

simctl delete is a real rm — the sim's app data is gone, not trashed, and is unrecoverable without a backup. Treat every sim with installed apps or a recent last-boot as in-use regardless of its iOS version.

Presenting the report

After running the script, relay the findings to the user as a clear report. Lead with the bottom line, then the breakdown:

1. Headline — current free space and total reclaimable (SAFE + CAUTION).
2. Ranked table — the script's size-ordered list, biggest first. The top few rows are where the real space is; focus attention there.
3. Guardrails — explicitly call out the PROTECT items and the PROTECT-newest runtime so the user knows what to leave alone.
4. Next step — since this skill only scans, end by asking the user what they want to do with the findings (e.g. proceed to a guided cleanup of the SAFE tier). Do not delete anything from within this skill.

Keep the framing honest: these are typical-vs-actual numbers from the user's own machine, and the severity tiers are about reversibility, not just size.