How to Use Mole's Project Artifact Purge Feature to Reclaim Disk Space

Mole's purge command scans your development directories for heavy build artifacts like node_modules and target folders, then presents an interactive menu to safely remove them while protecting essential system directories.

The Mole CLI by tw93 includes a specialized purge feature designed to reclaim disk space by removing accumulated build artifacts from development projects. This tool targets heavyweight directories such as node_modules, Rust target folders, and compiled binaries while implementing safety checks to prevent accidental deletion of critical system files. Understanding how to configure and execute this feature helps maintain clean development environments without risking your active projects.

How the Purge Pipeline Works

The purge feature operates as a self-contained pipeline defined across several modular shell scripts in the tw93/Mole repository.

Command Entry Point (bin/purge.sh)

When you run mo purge, the entry point script at bin/purge.sh initializes the process. It sets up temporary statistics tracking, displays a live spinner during scanning, and delegates core logic to the project cleaning module.

Configuration Loading (lib/clean/project.sh)

The load_purge_config() function in lib/clean/project.sh handles configuration discovery. On first run, if ~/.config/mole/purge_paths does not exist, the script auto-discovers candidate directories by looking for common project markers like package.json or Cargo.toml, then writes a default configuration file to the user's config directory.

Target Discovery and Scanning

Canonical purge targets—folder names like node_modules, target, bin, and build—are defined in lib/clean/purge_shared.sh. The scan_purge_targets() function in lib/clean/project.sh searches PURGE_SEARCH_PATHS using fd (with find as fallback) to locate these directories. Results pass through filter_protected_artifacts and filter_nested_artifacts to eliminate duplicates and system-critical paths.

Protection Logic

Before displaying results, is_protected_purge_artifact() applies language-specific protection rules. It excludes .NET bin directories, Composer/Rails/Go vendor folders, and Xcode DerivedData caches to prevent breaking active development environments.

Running the Mole Purge Command

The purge interface supports multiple modes to accommodate different workflows.

Basic Interactive Usage

Execute the standard command to start an interactive session:

mo purge

This initiates a scan of configured paths, then presents a menu showing each artifact with its size. Select specific entries for deletion or abort the operation entirely.

Preview Changes with Dry-Run Mode

To review what would be deleted without making changes, use the --dry-run flag:

mo purge --dry-run

The command still calculates and displays the total size that would be freed, but sets the internal $MO_DRY_RUN flag to prevent actual deletion.

Customizing Search Directories

Manage scan paths using the built-in configuration editor:

mo purge --paths

This opens ~/.config/mole/purge_paths in your default editor. The file supports one directory per line with ~ expansion:

# Custom scan roots

~/Work
~/Side-projects

Alternatively, override paths temporarily via environment variable:

PURGE_SEARCH_PATHS=("$HOME/Projects/Go") mo purge

Safety Mechanisms and Logging

Mole implements multiple safeguards to prevent data loss. The protection filters in is_protected_purge_artifact() distinguish between build artifacts and essential vendor directories. All deletion operations execute through remove_path() in lib/core/file_ops.sh and append entries to ~/Library/Logs/mole/operations.log for audit purposes.

Enable debug output to view underlying scan commands:

MO_DEBUG=1 mo purge

Summary

• The purge feature targets heavy build artifacts like node_modules, target, and bin directories through bin/purge.sh and lib/clean/project.sh.
• Configuration lives in ~/.config/mole/purge_paths, auto-generated on first run by load_purge_config().
• The scan_purge_targets() function uses fd or find to locate candidates, filtered by is_protected_purge_artifact() to exclude system-critical directories.
• Use mo purge --dry-run to preview deletions without risk, and mo purge --paths to customize search roots.
• All operations are logged to ~/Library/Logs/mole/operations.log for accountability.

Frequently Asked Questions

What directories does Mole scan by default?

On first execution, Mole auto-discovers directories containing recognized project markers like package.json, Cargo.toml, or pom.xml and stores these roots in ~/.config/mole/purge_paths. You can modify this list manually or via the mo purge --paths command.

How does Mole prevent deleting important files?

The is_protected_purge_artifact() function in lib/clean/project.sh maintains a whitelist of protected patterns, excluding language-specific vendor directories (like Go vendor folders) and system caches (like Xcode DerivedData) from the deletion menu.

Can I see what would be deleted before committing?

Yes. Run mo purge --dry-run to display the interactive menu and calculate total reclaimable space without executing any deletions. This sets the $MO_DRY_RUN flag which blocks the actual removal operations in remove_path().

Where does Mole log its deletion operations?

Every file removal is recorded in ~/Library/Logs/mole/operations.log by the remove_path() function in lib/core/file_ops.sh, providing an audit trail of all purge activities performed by the tool.

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