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

> Learn how to use Mole's project artifact purge feature to safely delete build artifacts like node_modules and reclaim disk space with an interactive menu.

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

---

**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`](https://github.com/tw93/Mole/blob/main/bin/purge.sh))

When you run `mo purge`, the entry point script at [`bin/purge.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/lib/clean/project.sh))

The `load_purge_config()` function in [`lib/clean/project.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/package.json) or [`Cargo.toml`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/lib/clean/purge_shared.sh). The `scan_purge_targets()` function in [`lib/clean/project.sh`](https://github.com/tw93/Mole/blob/main/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:

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

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

```bash
mo purge --paths

```

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

```text

# Custom scan roots

~/Work
~/Side-projects

```

Alternatively, override paths temporarily via environment variable:

```bash
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`](https://github.com/tw93/Mole/blob/main/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:

```bash
MO_DEBUG=1 mo purge

```

## Summary

- The purge feature targets heavy build artifacts like `node_modules`, `target`, and `bin` directories through [`bin/purge.sh`](https://github.com/tw93/Mole/blob/main/bin/purge.sh) and [`lib/clean/project.sh`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/package.json), [`Cargo.toml`](https://github.com/tw93/Mole/blob/main/Cargo.toml), or [`pom.xml`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/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`](https://github.com/tw93/Mole/blob/main/lib/core/file_ops.sh), providing an audit trail of all purge activities performed by the tool.