rusty-sweeper 0.3.1

A Linux disk usage management utility
Documentation

Rusty Sweeper

A fast, interactive disk usage analyzer and cleaner for Linux.

Current Status

Rusty Sweeper is implemented and test-covered across its main command surface:

  • rusty-sweeper is the interactive product and launches the TUI directly.
  • rusty-sweeper-monitor is a dedicated monitor binary with one-shot checks, daemon mode, PID/log management, and multiple notification backends.

Current limitations:

  • Some configuration sections remain informational, but scanner and TUI cleaner settings are active.
  • Cleanup and scan engines still exist in the codebase, but they are no longer exposed as standalone CLI subcommands.

Features

  • Interactive TUI: Browse disk usage and clean directly from the terminal
  • Monitor Service: Background daemon with desktop notifications when disk is full

Installation

From crates.io

cargo install rusty-sweeper

From Source

git clone https://github.com/lelloman/rusty-sweeper
cd rusty-sweeper
cargo install --path .

Usage

Interactive TUI

# Launch TUI in the current working directory
rusty-sweeper

# Scan a specific directory instead of the current working directory
rusty-sweeper /path/to/scan

# `rusty-sweeper` is the only user-facing mode of the main binary

Monitor Disk Usage

# Check once and exit
rusty-sweeper-monitor --once

# Start as daemon
rusty-sweeper-monitor --daemon

# Custom thresholds (warn at 70%, critical at 85%)
rusty-sweeper-monitor --warn 70 --critical 85

# Check daemon status
rusty-sweeper-monitor --status

# Stop daemon
rusty-sweeper-monitor --stop

Configuration

Configuration file: ~/.config/rusty-sweeper/config.toml

Scanner and TUI cleaner behavior is driven by the corresponding values.

Scanner parallelism, filesystem-boundary behavior, and the persistent metadata cache are active. Cached files are validated by device/inode, size, allocated blocks, and nanosecond modification/change times before their accounting is reused.

[scanner]
parallel_threads = 0  # 0 = auto
cross_filesystems = false
use_cache = true
cache_ttl = 3600

[cleaner]
project_types = ["cargo", "gradle", "maven", "npm", "go", "cmake", "python", "bazel", "dotnet"]
exclude_patterns = ["**/.git", "**/vendor"]
min_age_days = 0
max_depth = 10
parallel_jobs = 4

[monitor]
interval = 300  # seconds
warn_threshold = 80
critical_threshold = 90
mount_points = []
notification_backend = "auto"

[tui]
color_scheme = "auto"
show_hidden = false
default_sort = "size"
large_dir_threshold = 1073741824

TUI Keybindings

Scanning and cleanup run in background workers. The UI processes queued scan results in batches and redraws changed frames at most 60 times per second; keyboard input and terminal resizing are handled independently. Deleting an entry updates the in-memory tree without rescanning the root. Press r to refresh changes made outside the application.

If a deletion fails with a permission error, the TUI offers to retry that path with sudo. Accepting temporarily opens sudo's terminal password prompt, then returns to the TUI. Press n or Esc to leave the remaining files in place.

Key Action
j / Down Move down
k / Up Move up
Enter / l / Right Expand/enter directory
h / Left / Backspace Collapse/go up
d / Delete Delete selected
c Clean project
C Clean all eligible projects under selected directory
/ Search
s Cycle sort order
. Hide/show hidden files (shown by default)
r Rescan
? Help
Esc Cancel active work, otherwise quit
q Quit

Cleanup Support

The TUI can identify and clean common local build artifacts for Cargo, npm, Python, CMake, Gradle, Maven, and .NET projects. Docker system resources are also surfaced when available.

Systemd Service

To run the monitor as a systemd user service:

# Install the service
./dist/install-service.sh

# Enable and start
systemctl --user enable rusty-sweeper-monitor
systemctl --user start rusty-sweeper-monitor

# Check status
systemctl --user status rusty-sweeper-monitor

# View logs
journalctl --user -u rusty-sweeper-monitor -f

License

MIT