How to Customize Mole's Cleanup Targets: A Complete Guide

Customize Mole's cleanup targets by editing the MOLE_PURGE_TARGETS array in lib/clean/purge_shared.sh for what gets deleted, or use mo purge --paths to configure where Mole searches for those targets.

Mole is a fast, Rust-based CLI tool for cleaning up development environments. When you run mo purge, it hunts for heavy build artifacts across your filesystem. To effectively customize Mole's cleanup targets, you need to understand its two-layer architecture: the static target definitions (what gets deleted) and the configurable search paths (where to look).

Understanding Mole's Cleanup Architecture

Mole separates the cleanup logic into two distinct layers that you can customize independently:

Layer	Purpose	Configuration Location
Target Definitions	The list of directory names (e.g., node_modules, target, dist) that Mole identifies as deletable artifacts	lib/clean/purge_shared.sh – MOLE_PURGE_TARGETS array
Search Paths	The directories where Mole recursively searches for those target folders	~/.config/mole/purge_paths (managed via mo purge --paths)

Customizing What Gets Cleaned (The Targets)

The MOLE_PURGE_TARGETS array in lib/clean/purge_shared.sh defines the master list of folder names that mo purge will attempt to remove. By default, this includes common build artifacts like node_modules, target (Rust/Maven), build (Gradle), and dist.

Editing the Target Array

To modify what gets deleted, locate the MOLE_PURGE_TARGETS definition in lib/clean/purge_shared.sh:

readonly MOLE_PURGE_TARGETS=(
    "node_modules"
    "target"        # Rust, Maven

    "build"         # Gradle, various

    "dist"          # JS builds

    "venv"          # Python

    ".venv"
    ".pytest_cache"
    # … additional targets …

)

To add a target, append a new quoted string to the array. To remove a target, delete its line from the array.

Making Changes Permanent

Because MOLE_PURGE_TARGETS is declared as readonly at runtime, you must modify the source file before the script is sourced. For permanent changes:

1. Fork or clone the tw93/Mole repository
2. Edit lib/clean/purge_shared.sh to customize your MOLE_PURGE_TARGETS
3. Reinstall Mole from your fork using the standard install script

Customizing Where Mole Searches (The Paths)

You control which directories Mole scans for cleanup targets without modifying source code. Mole uses a configuration file at ~/.config/mole/purge_paths to store user-defined search paths.

Using the Interactive Configurator

The simplest way to customize search paths is using the built-in command:

mo purge --paths

This opens your default editor (configured via $EDITOR) with the purge_paths file, or creates it if it doesn't exist. Each line should contain one absolute path. The file supports tilde expansion (~ becomes $HOME).

Manual File Editing

You can also edit the file directly:

nano ~/.config/mole/purge_paths

The expected format is one absolute path per line:

# Mole Purge Paths - Auto-discovered project directories

# Edit this file to customize, or run: mo purge --paths

# Add one path per line (supports ~ for home directory)

~/Projects
~/Work
/Volumes/ExternalDrive/Repos

After saving, running mo purge will scan only these directories (and their subdirectories) for the targets defined in MOLE_PURGE_TARGETS.

Protecting Specific Folders with Whitelisting

If you need to ensure specific directories are never deleted—even if they match target names like node_modules—use the whitelist feature.

Add a path to the whitelist using:

mo clean --whitelist

This interactively adds paths to ~/.config/mole/whitelist. The is_path_whitelisted helper function checks this list before any deletion operation, protecting whitelisted directories from both mo clean and mo purge operations.

Complete Workflow Example

Here is a typical customization workflow combining all three methods:

# 1. Edit the target list (optional) – remove "vendor" if you never want to delete Composer packages

nano "$(git rev-parse --show-toplevel)/lib/clean/purge_shared.sh"

# 2. Define where Mole should look for projects

mo purge --paths      # edit ~/.config/mole/purge_paths

# 3. Whitelist a folder you never want removed

mo clean --whitelist  # interactively add e.g. ~/Projects/important/node_modules

# 4. Run a dry-run to see what will be removed

mo purge --dry-run

Technical Implementation Details

According to the tw93/Mole source code, the cleanup customization is implemented through four key mechanisms:

1. Loading defaults – project.sh sources purge_shared.sh and copies MOLE_PURGE_TARGETS into its own PURGE_TARGETS variable.

2. Resolving scan paths – The load_purge_config function reads ~/.config/mole/purge_paths via mole_purge_read_paths_config in purge_shared.sh. If the file is empty, Mole falls back to auto-discovery based on MOLE_PURGE_DEFAULT_SEARCH_PATHS.

3. Scanning – When mo purge executes, clean_project_caches iterates over PURGE_SEARCH_PATHS, recursively walks each tree, and identifies directories matching names in PURGE_TARGETS. Directories older than MIN_AGE_DAYS (default 7) are queued for deletion.

4. Whitelist protection – The is_path_whitelisted helper checks against ~/.config/mole/whitelist before any deletion, ensuring protected directories survive cleanup operations.

Summary

• Edit MOLE_PURGE_TARGETS in lib/clean/purge_shared.sh to change what folder names are considered purge‑able (requires source modification).
• Use mo purge --paths to configure where Mole searches for those targets via ~/.config/mole/purge_paths (no source code changes needed).
• Run mo clean --whitelist to protect specific directories from deletion by adding them to ~/.config/mole/whitelist.
• Test changes with mo purge --dry-run before executing destructive operations.

Frequently Asked Questions

How do I add a custom folder name like .cache to Mole's cleanup list?

To add a custom target like .cache, you must edit the MOLE_PURGE_TARGETS array in lib/clean/purge_shared.sh before installing or running Mole. Add "cache" or .cache to the array, then reinstall Mole from your modified source. There is currently no runtime configuration for adding new target names without modifying the source code.

Can I exclude specific directories from being scanned without whitelisting them?

Yes. Instead of using the whitelist (which prevents deletion of specific folders), you can control which top-level directories Mole scans by editing ~/.config/mole/purge_paths. Remove any paths you don't want scanned from this file. Mole will only recurse into directories explicitly listed in this configuration file or auto-discovered if the file is empty.

What happens if I delete ~/.config/mole/purge_paths?

If you delete the purge_paths file, Mole will fall back to its default behavior. According to the implementation in lib/clean/project.sh, when the configuration file is missing or empty, Mole uses MOLE_PURGE_DEFAULT_SEARCH_PATHS defined in purge_shared.sh to auto-discover common development directories under your $HOME folder.

How does the whitelist interact with the target list?

The whitelist acts as a final safety layer. When mo purge or mo clean runs, Mole first identifies directories matching the MOLE_PURGE_TARGETS names. Before deleting any directory, the is_path_whitelisted function checks if the path exists in ~/.config/mole/whitelist. If whitelisted, the directory is skipped regardless of whether it matches a target name or how old it is.

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