How Does Mole Perform Deep System Cleaning?

Mole performs deep system cleaning through a dedicated system-level module in lib/clean/system.sh that executes targeted deletion of aged caches, logs, and temporary files using sudo-protected wrapper functions while respecting user-defined whitelist rules.

Mole is an open-source macOS cleanup utility developed by tw93 that automates system maintenance through shell-based automation. When users invoke the clean command with elevated privileges, Mole initiates a comprehensive deep system cleaning pipeline that targets stale system data across ten distinct categories. This article examines the actual implementation, tracing how the clean_deep_system function safely reclaims disk space while maintaining system stability.

Entry Point: The mo clean Command Interface

The cleanup process begins in bin/clean.sh, which serves as the CLI entry point for all cleaning operations. At line 941, the script checks the SYSTEM_CLEAN environment variable and calls the clean_deep_system function when system-level maintenance is enabled.

The entry point validates sudo privileges before delegating to the system module. This ensures that file operations requiring root access—such as modifying /Library/Caches or /private/var/log—execute without permission errors.

Core Implementation: The clean_deep_system Pipeline

The heart of Mole’s deep cleaning logic resides in lib/clean/system.sh, starting at line 5. The clean_deep_system function orchestrates a sequential pipeline that targets specific macOS system directories, using age-based thresholds and safety wrappers to prevent accidental deletion of active files. Throughout execution, the function aggregates reclamation statistics in files_cleaned and total_size_cleaned variables to generate the final summary report.

System Caches and Temporary Files

Mole first targets system caches and temporary directories that accumulate over time. The implementation searches /Library/Caches for files matching *.cache, *.tmp, and *.log patterns older than $MOLE_TEMP_FILE_AGE_DAYS days, limited to a maximum depth of 5 levels.

For system temporary directories, the script loops through sys_temp_dirs (typically /private/tmp and /private/var/tmp), invoking safe_sudo_find_delete to remove files exceeding the configured age threshold.

Crash Reports and Diagnostic Logs

The pipeline specifically addresses diagnostic data stored in /Library/Logs/DiagnosticReports. Using safe_sudo_find_delete with the $MOLE_CRASH_REPORT_AGE_DAYS variable, Mole removes stale crash reports while preserving recent debugging information.

System logs under /private/var/log undergo similar treatment. The function executes three distinct safe_sudo_find_delete operations targeting .log, .gz, and .asl files within a depth limit of 3 directories.

Memory Exception Reports

Mole provides specialized handling for memory exception reports, first counting the files and calculating total size using stat before removal. This sub-step targets files older than 30 days, logging a summary of what will be deleted prior to execution. The implementation begins at line 74 of lib/clean/system.sh and ensures users understand exactly how much diagnostic data is being reclaimed from system directories.

Third-Party Application Logs

Beyond native macOS logs, Mole cleans third-party application data, specifically targeting Adobe and Creative Cloud log directories under /Library/Logs/. The implementation handles both directory-based logs and specific files like adobegc.log, ensuring creative professionals reclaim space from bloated application caches.

macOS Installer and Update Cleanup

Stale installation data represents significant disk usage. The script examines /Library/Updates for items that can safely be removed, skipping restricted system files through path validation.

For macOS installer applications, Mole identifies Install macOS*.app bundles and "macOS Install Data" folders older than 14 days using the get_file_mtime helper. Files meeting the age criteria undergo conditional removal via safe_sudo_remove.

Browser Code-Signature Caches and Power Logs

Mole targets ephemeral development artifacts including *.code_sign_clone directories scattered throughout /private/var/folders, implementing a 5-second timeout to prevent hanging on deeply nested file systems.

Diagnostic databases receive attention through cleanup of /private/var/db/diagnostics using $MOLE_LOG_AGE_DAYS to determine retention periods. Additionally, Mole clears accumulated power management data from /private/var/db/powerlog to remove stale energy diagnostics.

Safety Mechanisms and User Experience

Mole implements multiple safeguards to prevent data loss during deep system cleaning. The should_protect_path function validates every target against a user-defined whitelist and built-in protected paths before executing any deletion.

All removal operations use safe_sudo_remove or safe_sudo_find_delete wrappers defined in lib/core/sudo.sh. These functions trap errors gracefully, ensuring that permission conflicts or in-use files do not crash the cleaning process.

User experience remains central to the design. Spinner functions (start_section_spinner, stop_section_spinner) provide visual progress indicators during lengthy operations, while log_success and debug_log generate audit trails of reclaimed space.

How to Run Deep System Cleaning

Execute a dry-run to preview deletions without modifying system files. This command generates a preview list saved to ~/.config/mole/clean-list.txt, displaying exactly which aged caches and logs Mole will target.

mo clean --dry-run

To perform the actual deep system clean, invoke Mole with sudo privileges. Mole automatically requests admin rights if no active sudo session exists, then executes the full clean_deep_system pipeline.

sudo mo clean

For debugging or custom integration, source the library functions directly after loading the core environment. Note that direct invocation requires proper environment variables (such as MOLE_TEMP_FILE_AGE_DAYS) normally populated by the main entry point.

source "$HOME/.config/mole/lib/core/common.sh"
source "$HOME/.config/mole/lib/clean/system.sh"
clean_deep_system

Summary

• Mole performs deep system cleaning through a modular shell architecture centered in lib/clean/system.sh.
• The clean_deep_system function targets ten distinct categories including system caches, crash reports, memory exception logs, Adobe caches, and macOS installer leftovers.
• Safety wrappers (safe_sudo_remove, should_protect_path) ensure protected files remain untouched while operating under sudo privileges.
• Users can preview operations with --dry-run or execute full cleaning via sudo mo clean.
• All operations respect configurable age thresholds defined by MOLE_* environment variables.

Frequently Asked Questions

What specific directories does Mole target during deep system cleaning?

Mole targets system locations including /Library/Caches, /private/tmp, /private/var/log, /Library/Logs/DiagnosticReports, /Library/Updates, and third-party paths like Adobe log directories. The implementation specifically searches for file patterns such as *.cache, *.tmp, *.log, and *.code_sign_clone while respecting age thresholds configured through environment variables.

Is Mole's deep system cleaning safe for production machines?

Yes, according to the tw93/Mole source code, the implementation uses multiple safety layers. The should_protect_path function validates targets against whitelist rules before deletion, while safe_sudo_find_delete wrappers handle permission errors gracefully. Additionally, the --dry-run flag allows administrators to audit proposed deletions before execution.

How does Mole determine which files to delete versus preserve?

Mole uses time-based aging criteria defined by variables like MOLE_TEMP_FILE_AGE_DAYS, MOLE_CRASH_REPORT_AGE_DAYS, and MOLE_LOG_AGE_DAYS. Files older than these thresholds in designated system directories qualify for removal. The script also applies path depth limits (typically 3-5 levels) and specific pattern matching to avoid touching active system components.

Where can I find the source code for Mole's cleaning logic?

The primary implementation resides in lib/clean/system.sh, containing the clean_deep_system function and all sub-step definitions. The CLI entry point in bin/clean.sh (line 941) triggers this module when users run mo clean. Supporting utilities for sudo operations and logging live in lib/core/sudo.sh and lib/core/common.sh respectively.

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