Cleanroom is the Friction Lab tool for safe developer-cache cleanup.
The preferred public command is clean.
Cleanroom uses bundled cleanup profiles to describe known artifacts, categories, safety levels, and recommendations. Profiles are descriptive:
- Profiles explain what an artifact is
- Profiles explain why it may be safe or unsafe to clean
- Profiles explain expected impact and recommendations
- Profiles do not execute commands
- Profiles do not delete files
- Profiles do not move files
- Profiles do not bypass confirmation
- Profiles do not override allowed-root validation
Current bundled profile:
- Xcode
Install the binary:
cargo install --path . --force --bin cleanVerify the command:
which clean
clean --help 2>/dev/null || trueIf Cargo's bin directory is not on your PATH yet:
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcCheck required macOS tools:
command -v osascript
command -v openCheck the current Xcode cleanup roots:
ls -ld "$HOME/Library/Developer/Xcode/DerivedData" 2>/dev/null || echo "DerivedData not found"
ls -ld "$HOME/Library/Developer/Xcode/Archives" 2>/dev/null || echo "Archives not found"
ls -ld "$HOME/Library/Developer/Xcode/iOS DeviceSupport" 2>/dev/null || echo "iOS DeviceSupport not found"
ls -ld "$HOME/Library/Developer/Xcode/watchOS DeviceSupport" 2>/dev/null || echo "watchOS DeviceSupport not found"
ls -ld "$HOME/Library/Developer/Xcode/tvOS DeviceSupport" 2>/dev/null || echo "tvOS DeviceSupport not found"
ls -ld "$HOME/Library/Developer/Xcode/UserData/Previews" 2>/dev/null || echo "Previews not found"
ls -ld "$HOME/Library/Developer/Xcode/Products" 2>/dev/null || echo "Products not found"
ls -ld "$HOME/Library/Developer/Xcode/DocumentationCache" 2>/dev/null || echo "DocumentationCache not found"Check or create the log directory:
mkdir -p "$HOME/Library/Logs/Friction Lab/Cleanroom"
ls -ld "$HOME/Library/Logs/Friction Lab/Cleanroom"Notes:
cleandoes not need a shell wrapper. You can run it directly asclean.- Bundled profiles are loaded from the crate and used to annotate scan results in the TUI.
- Cleanup uses macOS Finder via
osascriptto move selected items to Trash. - Permanent delete is not implemented.
- Cleanup still requires explicit confirmation inside the TUI before anything is moved.
- If macOS prompts for folder access, allow Terminal, iTerm, or your terminal app to access the relevant folders.
- If scanning fails because of permissions, check System Settings -> Privacy & Security -> Files and Folders or Full Disk Access.
Current scope:
- Xcode cleanup only
Derived DataArchivesDevice Support(iOS,watchOS,tvOS)SwiftUI PreviewsProductsDocumentation CacheTest LogsResult Bundles- bounded
/private/tmpXcode build artifacts only (xcodebuild-*, matchingTemporaryItemsentries)
Current behavior:
- Scans bounded Xcode developer storage roots and summarizes size plus file counts by category
- Keeps the pass scan-first and review-first: categories are explained before cleanup
- Shows category-level safety, cleanup recommendation, caution text, default cleanup stance, and stale-first review hints in the TUI
- Uses profile metadata to explain categories and artifacts in the right-side summary panels
- High-confidence categories such as
Derived Data,SwiftUI Previews,Documentation Cache,Test Logs, andResult Bundlescan be pre-marked as cleanup candidates ArchivesandDevice Supportstay keep-by-default and high-caution- Entry review is stale-first and size-aware so older and heavier artifacts surface first
- Age-aware bulk review helpers can safely select
very stale,>30 day, or>90 dayentries before cleanup - Entry details include age labels and last-modified date labels when metadata is available
- Users can still review each category and choose what to keep
- Cleanup requires explicit confirmation
- Cleanup plans that include
ArchivesorDevice Supportrequire a typed high-caution confirmation before the final confirm screen - Default cleanup action moves items to macOS Trash
Category safety levels:
high confidence: generally safe generated developer storagemedium confidence: generated artifacts that still deserve reviewhigh caution: keep-by-default storage that may still matter for releases or device debugging
Cleanup recommendation badges:
Safe cleanup candidateReview carefullyKeep by default
Profile metadata includes:
- What an artifact or category represents
- Why it may be safe or unsafe to clean
- Whether it is selected by default for cleanup
- Whether cleanup is reversible and should move to Trash
- Caution text for review-first categories
- Expected impact after cleaning
- A recommendation for review or cleanup
Safety notes:
- Permanent delete is not implemented
- Cleanroom does not use
rm -rf - Entries are validated against known Xcode roots before cleanup
- Symlinks are skipped instead of followed blindly
- Missing folders produce zero-size findings instead of scan failures
/private/tmpscanning stays tightly bounded to clearly Xcode-related patterns- Archives and Device Support are not default cleanup targets in this pass
- Archives and Device Support still require an extra typed confirmation even if you manually mark them for cleanup
- Bulk age actions skip
ArchivesandDevice Supportby default - Cleanup profiles are descriptive only and cannot execute cleanup actions
- Cleanup logs are written to
~/Library/Logs/Friction Lab/Cleanroom/cleanroom.log
Review behavior:
- Categories keep a scan-first posture: totals, selected size, file count, safety, and stale signals are shown before cleanup
- Entry ordering favors very stale items first, then stale items, then size, then stable alphabetical order
- Category details and preview summaries include stale counts, very stale counts, and stale selected size
- Preview ordering also surfaces high-caution selections first so risky cleanup plans are obvious
- Missing modified-time metadata falls back to
Unknownwithout blocking scanning or cleanup preview - Bulk-generated selections can be cleared without undoing manual review choices
TUI review helpers:
- From the Xcode category summary action mode:
vselects very stale safe entries,3selects safe entries older than 30 days,9selects safe entries older than 90 days, anduclears generated bulk selections - From an entry checklist action mode: the same
v,3,9, anduhelpers apply only to the current safe category ArchivesandDevice Supportare still excluded from those bulk helpers unless you manually review and select them yourself- Cleanup remains explicit, Trash-only, and confirmation-gated after any bulk review action
Current development paths:
- Log path:
~/Library/Logs/Friction Lab/Cleanroom/cleanroom.log - Stats path:
~/Library/Application Support/Friction Lab/Cleanroom/stats.json - If legacy aggregate stats exist under the older PathPilot path, Cleanroom loads them and then writes future updates to the new Friction Lab stats path.
Aggregate stats:
- Stats path:
~/Library/Application Support/Friction Lab/Cleanroom/stats.json - Stats are aggregate-only
- Stats track cleanup counts, cleaned bytes, cleaned entries, and aggregate buckets such as
xcodeorxcode.derivedData - Stats do not store full private paths
- Stats are updated only after confirmed cleanup runs with successful Trash moves
- Stats write failures do not block cleanup completion
Optional testing helpers:
CLEANROOM_HOME_OVERRIDEpoints Xcode scanning at a fake home directory with the sameLibrary/...layoutCLEANROOM_LOG_PATHoverrides the default log pathCLEANROOM_STATS_PATHoverrides the aggregate stats path