sweep-cli 0.1.3
Find and clean build artifacts (node_modules, .venv, target, build) across all your projects. Interactive TUI, 10 ecosystems, git-aware safety.
License: MIT
Requires Python: >=3.8
Keywords: cleanup, disk, node_modules, devtools, cli

<div align="center">

# Sweep

**Most of your project folders are 90% junk. Sweep shows you exactly how much — and cleans it.**

[![PyPI](https://img.shields.io/pypi/v/sweep-cli?style=flat-square&color=blue)](https://pypi.org/project/sweep-cli/)
[![Downloads](https://img.shields.io/pypi/dm/sweep-cli?style=flat-square&color=green)](https://pypi.org/project/sweep-cli/)
![Python](https://img.shields.io/badge/Python-3.8+-3776AB?style=flat-square&logo=python&logoColor=white)
![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)
![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-orange?style=flat-square)

</div>

---

Developer project folders accumulate gigabytes of `node_modules/`, `.venv/`, `target/`, `build/`, and other build artifacts over time. Most of that disk space is **regenerable junk** that can be safely removed and restored with a single command.

Sweep scans your projects, compares the **full project size** against the **artifact size**, and shows you the exact **percentage of junk** in each project — then lets you reclaim it all interactively.

```
  SWEEP — 11 projects | 19.0 GB reclaimable (93% junk)

  PROJECT                        TYPE         FULL SIZE      ARTIFACTS   % JUNK
  ────────────────────────────────────────────────────────────────────────────────
  cloud-dashboard                 Next.js        13.1 GB       12.8 GB    97.7%
  pulse-mobile                    Flutter         3.1 GB        3.0 GB    96.8%
  nexus-admin                     Node.js         1.7 GB        1.6 GB    94.1%
  microkit-api                    Next.js       580.0 MB      556.8 MB    96.0%
  datastream-scraper              Node.js       315.0 MB      310.2 MB    98.5%
  ────────────────────────────────────────────────────────────────────────────────
  TOTAL                                          20.5 GB       19.0 GB    92.7%

  You can reclaim 19.0 GB out of 20.5 GB (93% is junk)

  [Space] select  [a] all  [Enter] delete  [q] quit
```

> `cloud-dashboard` is 13.1 GB, but 97.7% of that is just `node_modules/` and `.next/` cache. The actual source code is only ~300 MB.

## Installation

```bash
pip install sweep-cli
```

## Usage

```bash
# Scan the current directory
sweep

# Scan a specific path
sweep ~/projects

# Dry run — display results without launching the interactive TUI
sweep ~/projects --dry-run

# Output results as JSON (useful for scripting)
sweep ~/projects --json

# Only show projects with 100 MB+ of artifacts
sweep --min-size 100MB

# Only show projects not modified in the last 6 months
sweep --older-than 6m

# Limit the scan depth
sweep --depth 3
```

## Output Breakdown

For each detected project, Sweep displays:

| Column | Description |
|--------|-------------|
| **FULL SIZE** | Total size of the entire project directory |
| **ARTIFACTS** | Total size of deletable build artifacts (`node_modules/`, `.venv/`, `target/`, etc.) |
| **% JUNK** | Percentage of the project that consists of regenerable artifacts |

In most cases, **80-98% of a project's disk usage is artifacts** — files that are automatically regenerated by running `npm install`, `pip install`, `cargo build`, or equivalent commands.

## Interactive TUI

Sweep includes a built-in interactive terminal interface for browsing and selecting projects:

| Key | Action |
|-----|--------|
| `↑` `↓` / `j` `k` | Navigate the project list |
| `Space` | Toggle selection on the current project |
| `a` | Select all / deselect all |
| `s` | Sort by artifact size |
| `d` | Sort by last modified date (oldest first) |
| `n` | Sort alphabetically by name |
| `Enter` | Confirm and delete selected artifacts |
| `q` / `Esc` | Quit without deleting |

**Color coding:**
- **Green** — selected for deletion
- **Red** — project has uncommitted git changes (proceed with caution)

## Supported Ecosystems

Sweep detects **10 ecosystems** automatically:

| Ecosystem | Detected By | Artifacts Cleaned |
|-----------|-------------|-------------------|
| Node.js | `package.json` | `node_modules/` |
| Next.js | `next.config.*` | `.next/`, `node_modules/` |
| Python | `pyproject.toml`, `setup.py`, `requirements.txt` | `.venv/`, `venv/`, `__pycache__/`, `.tox/`, `.mypy_cache/` |
| Rust | `Cargo.toml` | `target/` |
| Go | `go.mod` | `vendor/` |
| Java (Maven) | `pom.xml` | `target/` |
| Java (Gradle) | `build.gradle` | `build/`, `.gradle/` |
| .NET | `*.csproj`, `*.sln` | `bin/`, `obj/` |
| Flutter | `pubspec.yaml` | `build/`, `.dart_tool/` |
| Ruby | `Gemfile` | `vendor/bundle/` |

## Git-Aware Safety

Sweep checks each project's git status before performing any deletion:

- **Clean** — no uncommitted changes; safe to delete artifacts
- **Dirty** — uncommitted changes detected; highlighted in red as a warning
- **No git** — projects without a git repository are displayed without a status indicator

All targeted artifacts (`node_modules/`, `.venv/`, `target/`, etc.) are fully regenerable and safe to remove. They can be restored at any time by running the appropriate install or build command.

## How It Works

1. Recursively walks the directory tree, looking for project marker files (`package.json`, `Cargo.toml`, `pyproject.toml`, etc.)
2. Identifies the ecosystem and locates the corresponding artifact directories
3. Calculates the **full project size** vs. **artifact size** to determine the **junk percentage**
4. Checks git status for each project to flag uncommitted changes
5. Presents results in a sortable, interactive TUI
6. Deletes only the selected artifacts — source code is never modified or removed

**Zero runtime dependencies** — built entirely on the Python standard library (`curses`, `os`, `shutil`, `argparse`).

## Support

If Sweep helped you reclaim disk space, consider supporting the project.

<a href="https://buymeacoffee.com/trinity_21" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="40"></a>

## License

MIT