deepclean 0.1.6

Fast, parallel Rust tool to clean Cargo target/ directories, remove unused dependencies, and free disk space from global toolchain caches (npm, Bun, cargo, pip, uv, Homebrew, HuggingFace, and more)
# deepclean ๐Ÿงน โ€” Fast Rust Cache Cleaner & Disk Space Recovery

**deepclean** is a fast, parallel command-line tool written in Rust that reclaims disk space by cleaning Cargo `target/` build directories, removing unused dependencies, and clearing global toolchain caches (npm, Bun, cargo, pip, uv, Homebrew, HuggingFace, Playwright, Puppeteer, and more).

It works as a `cargo` subcommand (`cargo deepclean`) and scans your projects in parallel across all CPU cores, so cleaning dozens of repositories takes seconds instead of minutes.

[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/yingkitw/deepclean)
[![Built with Rust](https://img.shields.io/badge/built%20with-Rust-orange.svg)](https://www.rust-lang.org/)

## Why deepclean?

Rust projects accumulate **gigabytes** of build artifacts in `target/` directories. A single workspace can consume 5โ€“10 GB; a folder of projects can eat 50+ GB. On top of that, global toolchain caches (npm's `_cacache`, Bun's install cache, HuggingFace model weights, Playwright browsers) silently grow to tens of gigabytes over months of development.

**deepclean solves three problems at once:**

- ๐Ÿš€ **Parallel Cargo cleaning** โ€” removes `target/` directories across many projects simultaneously, using all CPU cores.
- ๐Ÿงน **Unused dependency removal** โ€” detects and optionally removes dependencies in `Cargo.toml` that your source code no longer uses, speeding up builds.
- ๐Ÿ’พ **Global cache cleaning** โ€” lists npm, Bun, cargo, pip, uv, Homebrew, HuggingFace, and other caches with estimated reclaimable sizes, then lets you interactively pick which to clean.

## Quick Start

### Install

```bash
# From source (recommended for latest features)
git clone https://github.com/yingkitw/deepclean.git
cd deepclean
cargo install --path .

# Or directly from the repository
cargo install --git https://github.com/yingkitw/deepclean.git
```

> **Note:** Ensure `~/.cargo/bin` is on your `PATH` so the `cargo deepclean` subcommand is found.

### First run

```bash
# Clean target/ directories in the current folder and all subfolders
cargo deepclean

# Preview what would be cleaned (no deletion)
cargo deepclean --dry-run
```

## Features

### Cargo project cleaning

- โœ… **Parallel processing** โ€” cleans multiple projects simultaneously across all CPU cores
- โœ… **Smart workspace detection** โ€” scans `Cargo.toml` manifests to collapse workspace members to their root, no subprocesses required
- โœ… **Size filtering** โ€” `--min-size 100MB` cleans only projects above a threshold
- โœ… **Exclude patterns** โ€” skip directories with glob patterns (`-e "**/node_modules"`)
- โœ… **Dry-run mode** โ€” preview exactly what would be cleaned before deleting
- โœ… **Progress bars** โ€” real-time progress via `indicatif`
- โœ… **JSON output** โ€” machine-readable results for scripts and CI

### Unused dependency detection

- โœ… **Built-in detection** โ€” parses `Cargo.toml` and scans source code; no external tools required
- โœ… **Report mode** โ€” `--clean-deps` lists unused dependencies
- โœ… **Auto-remove** โ€” `--remove-deps` removes them (requires `cargo-edit`)

### Global toolchain cache cleaning (new)

- โœ… **Discovers 44 caches** โ€” npm, Bun, pnpm, Yarn, Deno, node-gyp, Vercel CLI, Cypress, Electron, Prisma, Chrome DevTools MCP, Selenium, cargo registry/git, sccache, pip, uv, Poetry, Conda, NuGet, Gradle, Maven, JVM shared cache, Homebrew, HuggingFace, PyTorch, Puppeteer, Playwright, go-build, Go modules, Xcode DerivedData/DeviceSupport, iOS Simulator, SwiftPM, CocoaPods, JetBrains, VS Code-family editors, Bazel, Zig, GitHub CLI, ChromaDB, codex-runtimes, opencode
- โœ… **Estimated sizes** โ€” shows reclaimable disk space per cache, computed in parallel
- โœ… **Risk tagging** โ€” each cache is marked **safe** (re-fetches on demand) or **heavy** (re-download required, e.g. model weights or browser binaries)
- โœ… **Interactive selection** โ€” pick caches by number, type `all`, or `q` to quit
- โœ… **Non-interactive mode** โ€” `--caches --all` cleans every safe cache without prompting
- โœ… **Dry-run and JSON** โ€” preview without deleting, or emit JSON for automation

## CLI Options

| Option | Description |
|--------|-------------|
| `[DIRECTORY]` | Directory to start cleaning from (default: `.`) |
| `-j, --jobs <N>` | Number of parallel jobs (default: CPU count) |
| `-e, --exclude <PATTERN>` | Exclude directories matching a glob pattern (repeatable) |
| `--dry-run` | Preview mode โ€” no changes are made |
| `--min-size <SIZE>` | Only clean projects above this size (e.g. `100MB`, `1GB`) |
| `--clean-deps` | Detect and report unused dependencies |
| `--remove-deps` | Remove unused dependencies (requires `cargo-edit`) |
| `--caches` | List global toolchain caches and interactively select which to clean |
| `--all` | With `--caches`: clean all safe caches non-interactively (heavy caches skipped) |
| `--interactive` | Prompt for confirmation before cleaning projects |
| `-v, --verbose` | Verbose output |
| `--json` | Output results as JSON |
| `-h, --help` | Print help |

## Usage Examples

### Clean all Cargo projects in a directory tree

```bash
cargo deepclean /path/to/projects
```

### Clean only large projects (above 500 MB)

```bash
cargo deepclean --min-size 500MB
```

### Preview without deleting (dry run)

```bash
cargo deepclean --dry-run
```

### Find and remove unused dependencies

```bash
# Detect only
cargo deepclean --clean-deps

# Detect and remove (requires cargo-edit)
cargo deepclean --remove-deps
```

### Exclude specific directories

```bash
cargo deepclean --exclude "**/target/debug" --exclude "**/node_modules"
```

### Limit parallelism

```bash
cargo deepclean -j 8
```

### Clean global toolchain caches

Beyond per-project `target/` directories, dev toolchains accumulate large global caches. `--caches` discovers them, shows their sizes, and lets you interactively pick which to clean:

```bash
# Interactive: pick caches by number, 'all', or 'q' to quit
cargo deepclean --caches

# Preview without deleting
cargo deepclean --caches --dry-run

# Non-interactive: clean every safe cache, no prompts (heavy caches skipped)
cargo deepclean --caches --all

# Machine-readable list of discovered caches (JSON array)
cargo deepclean --caches --json

# Clean safe caches and report results as JSON (automation/CI)
cargo deepclean --caches --all --json
```

Each cache is tagged **safe** (pure download cache that re-fetches on demand) or **heavy** (model weights, browser binaries, or runtimes that must re-download). Caches are removed with `rm -rf` and regenerated automatically by their tools on next use. `--caches --all` never touches heavy caches โ€” clean those via the interactive selection.

#### Supported caches

| Category | Caches |
|----------|--------|
| Rust | cargo registry cache, cargo registry src, cargo git checkouts, sccache |
| Python | pip, uv, Poetry, Conda pkgs |
| JS/TS | npm (`_cacache` + `_npx`), Bun, pnpm, Yarn, Deno, node-gyp, Vercel CLI, Cypress, Electron, Prisma engines, Chrome DevTools MCP, Selenium Manager |
| .NET | NuGet packages |
| Java | Gradle caches, Maven repository, JVM shared class cache |
| Apple | Xcode DerivedData, Xcode DeviceSupport, iOS Simulator, SwiftPM, CocoaPods |
| IDE | JetBrains caches, VS Code-family editor caches (Code, Insiders, VSCodium, Cursor, Windsurf, Trae, Qoder, Positron, Kiro, Void) |
| Other | Homebrew, Puppeteer, Playwright (+ ms-playwright-mcp), HuggingFace, PyTorch models, go-build, Go modules, Bazel, Zig, GitHub CLI, ChromaDB, codex-runtimes, opencode |

### JSON output for automation and CI

```bash
cargo deepclean --json
cargo deepclean --caches --json
```

When `--clean-deps` is enabled, each entry in `results` also carries an
`unused_deps` array (`name`, `location`) with the detection findings. The field
is omitted entirely when dependency detection did not run, so existing JSON
consumers see a stable shape.

`--caches --json` emits the discovered caches as a JSON array of
`{ id, name, category, risk, size_bytes, note }` entries. With `--caches --all
--json`, the output is instead a JSON array of clean results
(`{ id, name, success, freed_bytes, error }`), one per safe cache โ€” dry-run
included (`success: true`, nothing deleted).

## How It Works

1. **Discovery** โ€” recursively finds all `Cargo.toml` files using `walkdir` and resolves workspace membership by scanning manifests for `[workspace]` tables (no external commands).
2. **Filtering** โ€” applies exclude patterns and optional `--min-size` threshold.
3. **Cleaning** โ€” removes `target/` directories in parallel via `rayon`; falls back to direct `rm -rf` if `cargo clean` fails.
4. **Dependency analysis** โ€” parses `Cargo.toml` and scans `src/`, `examples/`, `tests/`, and `build.rs` for dependency usage; reports or removes unused crates.
5. **Cache cleaning** (`--caches`) โ€” scans known global cache locations, computes sizes in parallel, presents an interactive selection, and removes chosen caches. `--caches --all` skips the prompt and cleans every safe cache.

## Requirements

- **Rust toolchain** and **Cargo** (for installation and project cleaning)
- **Optional:** [`cargo-edit`]https://github.com/killercup/cargo-edit for `--remove-deps` (detection works without it)

```bash
cargo install cargo-edit
```

## Performance

deepclean is built in Rust for maximum performance:

- **Parallel execution** across all CPU cores via `rayon`'s work-stealing scheduler
- **Efficient directory traversal** with `walkdir` and early pruning of hidden/excluded dirs
- **Parallel size calculation** for global cache discovery
- **Minimal memory footprint** โ€” streams results rather than buffering

## FAQ

### Is deepclean safe to use?

Yes. `--dry-run` previews every change without deleting anything. Project cleaning removes only `target/` directories (regenerated by the next `cargo build`). Cache cleaning removes only the listed cache directories, which tools re-create on next use. The `--interactive` flag adds a confirmation prompt before cleaning projects.

### Does deepclean modify my source code?

Only when you explicitly pass `--remove-deps`, which edits `Cargo.toml` to remove unused dependencies. Without that flag, deepclean only deletes `target/` directories and (with `--caches`) global cache directories.

### How is deepclean different from `cargo clean`?

`cargo clean` cleans a single project. deepclean finds and cleans **all** projects in a directory tree in parallel, detects unused dependencies, and cleans global toolchain caches โ€” none of which `cargo clean` does.

### Which caches does `--caches` support?

npm, Bun, pnpm, Yarn, Cypress, Electron, cargo registry, pip, uv, Poetry, Gradle, Maven, Homebrew, Puppeteer, Playwright, HuggingFace, PyTorch, go-build, Go modules, Xcode DerivedData, and codex-runtimes. See the [Supported caches](#supported-caches) table above.

### Can I use deepclean in CI?

Yes. Use `--json` for machine-readable output and `--dry-run` for safe previews. The exit code is non-zero if any cleaning operation fails.

## Contributing

Contributions are welcome! Please open issues or submit pull requests at [github.com/yingkitw/deepclean](https://github.com/yingkitw/deepclean).

## License

Apache-2.0

## Links

- **Repository:** [github.com/yingkitw/deepclean]https://github.com/yingkitw/deepclean
- **Documentation:** [docs.rs/deepclean]https://docs.rs/deepclean
- **Crates.io:** [crates.io/crates/deepclean]https://crates.io/crates/deepclean