How to Clean Installer Files with Mole: A Complete Guide

To clean installer files with Mole, run mo clean which triggers the clean_deep_system function in lib/clean/system.sh to scan for macOS installer apps and data folders older than 14 days, safely removing them with safe_sudo_remove while respecting active processes and whitelist protections.

Mole is an open-source macOS cleanup utility maintained by tw93/Mole that automates the removal of system debris, including stale macOS installer applications. This guide explains exactly how Mole identifies and cleans installer files, where the logic resides in the source code, and how to execute dry-runs or configure protections.

How Mole Cleans macOS Installer Files

When you execute mo clean, the command invokes bin/clean.sh, which acts as the main driver. This script initializes a sudo session via lib/core/sudo.sh and then delegates to lib/clean/system.sh to perform deep system cleaning.

Inside lib/clean/system.sh, the clean_deep_system function orchestrates the scan. For installer files specifically, it executes two distinct detection passes:

1. Install Data Folders: Checks for /macOS Install Data directories at the root level.
2. Installer Applications: Enumerates bundles matching /Applications/Install macOS*.app.

The Detection Logic in lib/clean/system.sh

The source code at lines 97–149 of lib/clean/system.sh contains the specific logic for targeting installer artifacts.

For the data folder, the script uses a 14-day threshold. If the directory exists and its modification time exceeds 14 days, safe_sudo_remove is invoked:

# lib/clean/system.sh (lines 97-113)

if [[ -d "/macOS Install Data" ]]; then
  # Check if older than 14 days

  if [[ $(find "/macOS Install Data" -mtime +14) ]]; then
    safe_sudo_remove "/macOS Install Data"
  fi
fi

For installer applications, the loop at lines 121–148 iterates through matching app bundles, skipping any processes currently running via pgrep -f "$installer_app":

# lib/clean/system.sh (lines 121-148)

for installer_app in /Applications/Install\ macOS*.app; do
  # Skip if installer is currently running

  if pgrep -f "$installer_app" > /dev/null; then
    continue
  fi
  
  # Check age and calculate size

  if [[ $(find "$installer_app" -mtime +14) ]]; then
    size_kb=$(get_path_size_kb "$installer_app")
    safe_sudo_remove "$installer_app"
  fi
done

Safety Mechanisms: Process Checks and Whitelists

Mole implements two critical safeguards to prevent accidental deletion of active or protected installer files.

Process Detection: Before removing any installer application, the script executes pgrep -f "$installer_app" to verify the installer is not currently executing. If the process exists, the cleanup skips that bundle entirely.

Whitelist Protection: All removal operations route through safe_sudo_remove defined in lib/core/common.sh. This function consults the user whitelist (managed via lib/manage/whitelist.sh) prior to executing sudo rm -rf. Any path added to ~/.config/mole/whitelist is permanently excluded from cleanup operations.

Step-by-Step: Clean Installer Files with Mole

Use these commands to safely identify and remove stale macOS installer artifacts.

1. Preview What Would Be Removed

Execute a dry-run to see which installer files Mole would delete without actually removing them:

mo clean --dry-run | grep -i "installer"

This parses the output to show only lines related to installer apps or data folders.

2. Perform the Cleanup

Run the standard clean command to remove installer files older than 14 days:

mo clean

Mole will request your administrator password on the first run to establish a cached sudo session via lib/core/sudo.sh. The system cleanup module then executes clean_deep_system to process installer files.

3. Automate in Non-Interactive Environments

For CI pipelines or remote scripts, run system cleanup without prompts:

mo clean --non-interactive --system-only

The --system-only flag ensures Mole targets system-level debris including installer data folders, while --non-interactive suppresses the TUI spinner and confirmation prompts.

4. Protect Specific Installers from Deletion

To prevent Mole from removing a specific macOS installer, add its path to the whitelist:

echo "/Applications/Install macOS Ventura.app" >> ~/.config/mole/whitelist
mo clean

The safe_sudo_remove function in lib/core/common.sh will now skip this bundle during the age-check loop in lib/clean/system.sh.

Key Source Files and Functions

Understanding the source structure helps you customize or debug the installer cleanup behavior.

• bin/clean.sh: Main driver that parses CLI flags (--dry-run, --system-only), initializes the sudo session, and invokes perform_cleanup.
• lib/clean/system.sh: Contains clean_deep_system function. Lines 97–113 handle /macOS Install Data folders; lines 121–148 process Install macOS*.app bundles with process detection and size calculation.
• lib/core/common.sh: Defines safe_sudo_remove (whitelist checking and safe deletion) and get_path_size_kb (disk usage calculation).
• lib/core/sudo.sh: Manages cached sudo credentials and session cleanup. Used by bin/clean.sh before executing system-level removals.
• lib/manage/whitelist.sh: Management interface for the whitelist file at ~/.config/mole/whitelist.

Summary

• Mole cleans installer files through the clean_deep_system function in lib/clean/system.sh, triggered by the mo clean command.
• The script targets /macOS Install Data folders and /Applications/Install macOS*.app bundles older than 14 days.
• Process safety is enforced via pgrep checks to ensure running installers are never deleted.
• Whitelist protection routes all deletions through safe_sudo_remove in lib/core/common.sh, respecting user-defined exclusions.
• Use --dry-run to preview deletions and --non-interactive for automated scripting.

Frequently Asked Questions

Will Mole delete a macOS installer that I'm currently running?

No. The cleanup logic in lib/clean/system.sh explicitly checks for active processes using pgrep -f "$installer_app" before removal. If the installer application is currently executing, Mole skips that bundle and leaves it untouched.

How do I prevent Mole from deleting a specific installer?

Add the full path to the installer application to your whitelist file. Execute echo "/Applications/Install macOS [Version].app" >> ~/.config/mole/whitelist before running mo clean. The safe_sudo_remove function in lib/core/common.sh checks this whitelist prior to executing any deletion.

What happens if the installer files are less than 14 days old?

Mole preserves installer files that are newer than 14 days. Both the /macOS Install Data folder check (lines 97–113) and the application bundle loop (lines 121–148) in lib/clean/system.sh use find with -mtime +14 to enforce this retention period.

Is it safe to run mo clean on a system without backups?

While Mole implements safeguards like process detection and whitelists, any system-level cleanup tool carries inherent risk. The safe_sudo_remove function in lib/core/common.sh uses sudo rm -rf for final deletion, which is irreversible. It is recommended to run mo clean --dry-run first to review targets, maintain Time Machine or other backups, and verify your whitelist configuration before executing live cleanup operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}