How to Clean node_modules & Build Caches Safely Without Corrupting Git or Losing Work

The Danger of Blind Developer Cleanup

As macOS software engineers, our development directories (~/Developer, ~/Projects, ~/Code) routinely balloon to tens or hundreds of gigabytes. Heavy build artifacts—like node_modules, Rust target/ folders, Xcode DerivedData, Python .venv, and Go module caches—often sit right beside critical, uncommitted work.

Most developers clean these folders with blunt instruments:

find . -name "node_modules" -type d -prune -exec rm -rf '{}' +

While this command reclaims disk space, running it blindly without Git state awareness is dangerous. Here is what can go wrong:

• Active Git Rebases & Merges: If a rebase (REBASE_HEAD) or cherry-pick is in progress, deleting dependencies mid-flight can invalidate index references or trigger catastrophic merge conflicts.
• Untracked Files Lost Forever: Developers frequently place scratch files, prototype.swift, notes.md, or experimental scripts inside dependency trees. Generic cleaner tools treat untracked as disposable. In reality: untracked = unknown ownership/value.
• Process Locking & Partial Deletes: If Xcode, swiftc, node, cargo, or xcodebuild is actively compiling or hot-reloading when a deletion script runs, partial file locks can corrupt build caches or leave orphaned file handles.
• Accidental Metadata Destruction: One mistyped path pattern can purge the .git/ directory itself, obliterating your entire commit history, stashes, and remote tracking configurations.

The Solution: Git Safety Intelligence

Rather than acting as a redundant Git client, MacPilot introduces a Git Safety Intelligence Engine designed specifically for developer cleanup. Before removing a single file, it answers three fundamental questions:

1. What is this file? (Is it a regenerable build cache, an untracked scratchpad, or source code?)
2. What relationship does it have with Git? (Is it tracked, untracked, ignored, or part of .git repository metadata?)
3. What could the developer lose if it is removed?

The 4-State Safety Taxonomy

MacPilot evaluates every cleanup candidate through a target-aware risk model:

• SAFE: Regenerable dependency directories (e.g. node_modules, target/, .build/) that are outside Git tracking. Even if your working tree has uncommitted source edits, these directories are 100% safe to wipe and reinstall with your package manager.
• CAUTION: Untracked files or custom build outputs. MacPilot requires explicit developer review before touching anything not tracked by Git.
• PROTECTED: Git repository metadata (.git/, objects/, refs/, HEAD, config) and uncommitted modified source files. Strictly locked from automatic deletion.
• BLOCKED: Repositories undergoing active operations (MERGE_HEAD, REBASE_HEAD, CHERRY_PICK_HEAD, BISECT_LOG) or locked by active compilers (swiftc, clang, node, cargo). The operation is blocked until the Git operation finishes or the process releases its lock.

Safe Process Collision Audit via Darwin libproc

MacPilot does not rely on slow shell invocations. Using Darwin kernel APIs (proc_listpids, proc_name, and PROC_PIDVNODEPATHINFO), MacPilot inspects running processes in under 5 milliseconds. It verifies whether an active compiler or IDE has an open working directory inside the repository before performing any cleanup.

The Safe Cleanup Preview

Before any destructive action, MacPilot presents an interactive Safe Cleanup Preview sheet:

• Total gigabytes to be reclaimed.
• Clear separation between Safe Items (green checkmarks) and Protected Items (lock icons).
• Real-time banners highlighting active branch, ahead/behind sync, and process state.
• Safe movement to the macOS Trash via FileManager.trashItem rather than unrecoverable unlink.
• Immutable audit logging (GitCleanupRecord) to track every reclaimed byte.

You get the freedom of reclaiming 20 to 80 GB of developer bloat with the absolute confidence that your work, Git history, and active branches remain untouched.