How to Configure Mole's Protected Directories: A Complete Guide to the Whitelist System

Mole protects directories from accidental deletion by consulting a whitelist stored in ~/.config/mole/whitelist, which is checked by the is_path_whitelisted() function before any removal operation.

Mole is a macOS cleanup utility that safeguards system-critical folders and user data through a robust whitelist mechanism. Understanding how to configure these protected directories ensures you can safely clean caches and temporary files without risking important data.

How Mole's Directory Protection Works

Mole implements a three-tier protection system: default hard-coded patterns, user-editable configuration files, and runtime validation functions.

Default Protection Patterns

The built-in safeguards are defined in lib/core/base.sh as the DEFAULT_WHITELIST_PATTERNS array (lines 85-101). This serves as a fallback when no user configuration exists, protecting critical system directories such as caches, model data, and system folders.

User-Configurable Whitelist Files

Mole maintains separate whitelist files for different operations:

• ~/.config/mole/whitelist – Used by standard mo clean operations
• ~/.config/mole/whitelist_optimize – Used exclusively by mo optimize commands

These paths are defined in lib/manage/whitelist.sh lines 12-15 as WHITELIST_CONFIG_CLEAN and WHITELIST_CONFIG_OPTIMIZE.

Runtime Loading and Validation

The load_whitelist() function in lib/manage/whitelist.sh (lines 82-118) reads the whitelist file into the runtime array CURRENT_WHITELIST_PATTERNS. If a legacy file ~/.config/mole/whitelist_checks exists, it automatically migrates the content to the new location.

Before any deletion, is_path_whitelisted() (lines 44-60) performs an exact string match against CURRENT_WHITELIST_PATTERNS. Notably, Mole does not expand glob patterns—it compares the fully expanded path against stored patterns exactly, preventing unintended matches and security risks.

Where to Configure Protected Directories

The configuration depends on the operation mode:

File Path	Purpose	Source Reference
~/.config/mole/whitelist	Standard clean operations	lib/manage/whitelist.sh lines 12-13
~/.config/mole/whitelist_optimize	Optimization-specific skips	lib/manage/whitelist.sh lines 14-15
lib/core/base.sh	Hard-coded defaults	Lines 85-101 (DEFAULT_WHITELIST_PATTERNS)

How to Add or Remove Protected Directories

Mole offers two methods for modifying the whitelist: direct file editing and an interactive CLI.

Method 1: Direct File Editing

Edit the whitelist file directly to add custom protected paths:

# Create or append to the whitelist file

cat >> "$HOME/.config/mole/whitelist" <<'EOF'

# Personal protected directories

$HOME/Documents/ImportantProject
$HOME/Development/CriticalRepo
EOF

Verify that Mole recognizes the new entries:

mo clean --dry-run | grep "ImportantProject"

The output should indicate the directory is "skipped (whitelist)".

Method 2: Interactive CLI

Use the built-in interactive menu for visual management:

# Launch the whitelist manager for clean operations

mo clean --whitelist

For optimization-specific protections:

mo optimize --whitelist

Navigate using ↑/↓ keys, toggle selections with SPACE, and press ENTER to save. The CLI writes changes directly to the respective whitelist file in ~/.config/mole/.

Key Implementation Details

Understanding these technical specifics helps avoid configuration errors:

Exact String Matching – The is_path_whitelisted() function performs exact string comparisons ([[ "$check_pattern" == "$existing_expanded" ]]), not glob expansion. Patterns must match the full expanded path exactly.

Separate Optimization Whitelist – The optimize command uses a distinct whitelist (whitelist_optimize) that stores check names to skip (e.g., check_brew_health) rather than directory paths. This is loaded by bin/optimize.sh.

Automatic Migration – If ~/.config/mole/whitelist_checks exists from an older version, load_whitelist() automatically migrates its contents to the new standard location.

Core Clean Integration – In bin/clean.sh (line 92), the whitelist is loaded into WHITELIST_PATTERNS, and line 386 calls is_path_whitelisted before executing any deletion.

Summary

• Primary whitelist location: ~/.config/mole/whitelist for standard clean operations, ~/.config/mole/whitelist_optimize for optimization mode
• Default patterns: Defined in lib/core/base.sh as DEFAULT_WHITELIST_PATTERNS (lines 85-101)
• Configuration methods: Direct file editing or interactive CLI via mo clean --whitelist
• Matching behavior: Exact string comparison only—no glob expansion performed by is_path_whitelisted() in lib/manage/whitelist.sh
• Runtime loading: load_whitelist() in lib/manage/whitelist.sh (lines 82-118) populates the CURRENT_WHITELIST_PATTERNS array used by bin/clean.sh

Frequently Asked Questions

Where is the default whitelist defined in the Mole source code?

The default whitelist patterns are defined in lib/core/base.sh within the DEFAULT_WHITELIST_PATTERNS array (lines 85-101). These serve as fallback values when no user configuration exists at ~/.config/mole/whitelist.

Can I use wildcards or glob patterns in the whitelist file?

No. According to the is_path_whitelisted() implementation in lib/manage/whitelist.sh (lines 44-60), Mole performs exact string matching only ([[ "$check_pattern" == "$existing_expanded" ]]). Glob expansion is intentionally disabled for security reasons to prevent unintended matches.

What is the difference between whitelist and whitelist_optimize?

The ~/.config/mole/whitelist file controls which directories are protected during standard mo clean operations, while ~/.config/mole/whitelist_optimize stores check names to skip during mo optimize (such as check_brew_health). They are loaded by bin/clean.sh and bin/optimize.sh respectively.

How do I temporarily disable whitelist protection for a single run?

To bypass whitelist checks temporarily, you can run Mole with an empty whitelist file by setting the environment variable to /dev/null: MOLE_WHITELIST_FILE="/dev/null" mo clean --dry-run. Alternatively, for testing purposes, you can use the --dry-run flag to preview what would be deleted without actually removing anything, allowing you to verify whitelist behavior safely.

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