# How Does Mole Perform Deep System Cleaning?

> Discover how Mole performs deep system cleaning by targeting aged caches, logs, and temporary files. Learn about its secure system-level module and whitelist features.

- Repository: [Tw93/Mole](https://github.com/tw93/Mole)
- Tags: deep-dive
- Published: 2026-03-20

---

**Mole performs deep system cleaning through a dedicated system-level module in [`lib/clean/system.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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.

```bash
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.

```bash
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.

```bash
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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/lib/clean/system.sh)**, containing the `clean_deep_system` function and all sub-step definitions. The CLI entry point in **[`bin/clean.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/lib/core/sudo.sh) and [`lib/core/common.sh`](https://github.com/tw93/Mole/blob/main/lib/core/common.sh) respectively.