CleanSys - Modern System Cleaner (Linux, macOS, Windows)

CleanSys is a modern Linux system-cleanup utility available as both a terminal UI (Ratatui) and a desktop GUI (Iced). It helps you safely remove unnecessary files, clean caches, and free up disk space with real-time progress tracking.

🧱 Project Structure

CleanSys is a Cargo workspace with three crates:

Crate	Binary	Description
cleansys-core	(library)	Framework-free domain logic: cleaners, permission checks, formatting, sudo auth — shared by both front-ends
cleansys-tui	cleansys	Ratatui terminal UI + CLI (the original CleanSys experience) — published to crates.io as cleansys
cleansys-gui	cleansys-gui	Iced desktop GUI

🎬 Demo

Main Demo

![CleanSys Demo](demo

✨ Features

🛡️ Safety

• Confirmation dialog before any destructive run (TUI and GUI) — lists exactly what's selected, with an option to disable prompts (y in the TUI)
• Preview / dry-run mode — measure real sizes and paths that would be cleaned without deleting anything (d in the TUI, "Preview" button in the GUI)
• Progress tracking — live per-item status plus an overall progress bar/percentage while a run is in flight
• Desktop notifications on completion (Linux/macOS/Windows)

🎨 Modern Terminal UI

• Beautiful Interface: Built with Ratatui for a smooth, modern experience
• Interactive Checkboxes: Easy selection using tui-checkbox library
• Animated loading spinner: tui-spinner renders a live braille spinner in the title bar while a cleaning run is in progress
• Multiple Chart Types: Toggle between Bar Chart, Pie Chart (by count), and Pie Chart (by size) — rendered directly by tui-piechart, with no local pie-drawing code of our own
• Split-View Progress: Detailed status information with real-time updates
• Animated Indicators: Loading spinners, progress bars, and status icons
• Responsive Design: Automatically adapts to any terminal size
• Real-time Resize: Handles terminal resizing without losing state

🧹 User-Level Cleaning (Linux, macOS, Windows)

• Browser caches — Firefox, Chrome/Chromium, Edge, Safari (real per-platform paths, not guesses)
• Application caches
• Thumbnail/preview caches
• Temporary files owned by the current user
• Package manager caches (pip, npm, cargo)
• Trash / Recycle Bin (Linux XDG trash, macOS ~/.Trash, Windows Recycle Bin via Shell32)

🔧 System-Level Cleaning (platform-appropriate, some require root/admin)

• Linux: apt/pacman/dnf caches, rotated logs + journald vacuum, /var/cache, old kernels, crash reports
• macOS: Homebrew cache (never run as root!), Xcode DerivedData, unavailable iOS/watchOS/tvOS Simulator caches, rotated system logs, diagnostic/crash reports
• Windows: Windows Update download cache, C:\Windows\Temp, Recycle Bin (via the same Shell32 API Explorer's "Empty Recycle Bin" uses — no Administrator required for the current user's own bin)

Every cleaner reports real measured sizes — no estimates or guesses — and the detailed view/GUI activity log lists exactly which files/directories were removed and how many bytes each one freed.

🛡️ Safe by Default

• Never removes system-critical files
• Confirms before running operations
• Detailed logs of all actions
• Shows exactly what will be cleaned
• Individual cleaner selection

📦 Installation

From crates.io

# Terminal UI + CLI
cargo install cleansys

# Desktop GUI
cargo install cleansys-gui

From source

git clone https://github.com/sorinirimies/cleansys
cd cleansys

# Build everything
cargo build --workspace --release

# Or install just one front-end
cargo install --path crates/cleansys-tui
cargo install --path crates/cleansys-gui

See justfile for the full list of development tasks (just --list).

🚀 Usage

Interactive TUI (Default)

Simply run CleanSys to launch the interactive terminal interface:

# User-level cleaning
cleansys

# System-level cleaning (requires root)
sudo cleansys

Desktop GUI

Prefer a graphical interface? Launch the Iced-based desktop app instead:

cleansys-gui

It presents the exact same cleaners as the TUI (shared via cleansys-core) with checkboxes per category, a "Run selected" button, and a live activity log. Selections are remembered across restarts. System cleaners will prompt for your sudo password (Unix) or an "Administrator required" notice with a one-click relaunch (Windows) the first time they're needed.

• Confirm before cleaning: clicking "Run selected" shows exactly what's about to be deleted before anything happens.
• Preview: click "Preview" to see real sizes/paths that would be cleaned without deleting anything.
• Progress bar: a live progress bar and "N/M" counter while a run (or preview) is in flight.
• Global selection: "Select all" / "Select none" buttons work across every category, not just the active tab.
• Desktop notification when a run finishes.

The top bar includes a theme selector with 43 built-in themes (Dracula, Nord, Solarized, Gruvbox, Catppuccin, Tokyo Night, Kanagawa, Rose Pine, and more) — pick one from the dropdown and it's applied instantly and remembered across restarts (saved to ~/.config/cleansys/settings.json).

Command-Line Interface

# Run terminal UI explicitly
cleansys tui

# Run text-based interactive menu
cleansys menu

# Run user-level cleaners with confirmation
cleansys user

# Run user-level cleaners without prompts
cleansys user --yes

# Run system-level cleaners (requires root)
sudo cleansys system

# Run system cleaners without prompts
sudo cleansys system --yes

# List all available cleaners
cleansys list

# Show verbose output
cleansys --verbose

⌨️ Terminal UI Controls

Navigation

• ↑/↓ or j/k: Navigate items
• Tab/Shift+Tab: Switch between categories
• j/k: Scroll detailed items list (vi-style)
• PgUp/PgDn: Scroll operation log
• Home/End: Jump to first/last item

Actions

• Space: Toggle selection
• Enter: Run selected cleaners (shows a confirmation overlay first, unless disabled)
• d: Preview selected cleaners (dry-run — measures real sizes/paths, deletes nothing)
• a: Select all in current category
• n: Deselect all in current category
• A: Select all across every category
• N: Deselect all across every category
• y: Toggle confirmation prompts on/off
• ESC: Cancel operation, close overlay, or return to menu
• q: Exit application

View Controls

• c: Cycle chart types (Bar → Pie Count → Pie Size)
• m: Toggle compact mode
• v: Cycle view modes (Standard/Compact/Detailed/Performance)
• p: Toggle performance statistics
• s: Toggle auto-scroll log
• /: Toggle search in detailed view
• ?: Show/hide help

📱 Responsive Design

CleanSys features a fully responsive terminal interface with multiple breakpoints:

Terminal Width	Layout Features
< 60 columns	Minimal UI, chart hidden, essential information only
60-79 columns	Compact layout with reduced chart
80-119 columns	Balanced layout with full chart
120+ columns	Spacious layout with maximum information density

🎯 View Modes

• Standard Mode: Balanced layout with full feature visibility (default)
• Compact Mode: Condensed layout for smaller terminals (<25 rows)
• Detailed Mode: Maximum information density with extended statistics
• Performance Mode: Focus on operation metrics and real-time monitoring

📊 Chart Visualization

Press c to cycle through different chart types:

1. Bar Chart: Traditional vertical bar chart showing cleaned items
2. Pie Chart (Count): Distribution by number of items cleaned
3. Pie Chart (Size): Distribution by bytes cleaned

All charts automatically adapt to terminal size and include:

• Percentages
• Legends
• Color coding
• Smart label positioning

🔍 Detailed View

After cleaning operations, view comprehensive details:

• Complete list of cleaned files and directories
• Full file paths
• Individual file sizes
• Timestamps
• Scrollable with j/k or PgUp/PgDn
• Search functionality with /

📝 Examples

Interactive TUI

# Launch TUI (default behavior)
cleansys

# Navigate with arrow keys
# Select cleaners with Space
# Press Enter to run

Quick Clean

# Clean user caches without prompts
cleansys user --yes

# Clean system caches with verbose output
sudo cleansys system --verbose --yes

List Available Cleaners

cleansys list

Output:

AVAILABLE CLEANERS

User cleaners (no root required):
  • Browser Caches
  • Application Caches
  • Thumbnail Caches
  ...

System cleaners (root required):
  • Package Manager Caches
  • System Logs
  • System Caches
  ...

🏗️ Architecture

CleanSys is a Cargo workspace of three crates — see Project Structure above. Rough internal layout:

crates/
├── cleansys-core/           # Shared, framework-free logic
│   └── src/
│       ├── cleaners/        # user_cleaners.rs, system_cleaners.rs, cleaned_item.rs
│       ├── model.rs         # CleanerItem, CleanerCategory, Status, load_categories()
│       ├── auth.rs          # Sudo authentication helper
│       └── utils.rs         # Permissions, formatting, confirmation prompts
├── cleansys-tui/            # Ratatui TUI + CLI (binary: cleansys)
│   └── src/
│       ├── app.rs           # Application state and key-handling logic
│       ├── events.rs        # Terminal input/resize event handling
│       ├── render.rs        # UI rendering logic
│       ├── pie_chart.rs     # Thin adapter: our data -> tui-piechart::PieChart (no local drawing logic)
│       ├── menu.rs          # Text-based interactive menu
│       └── components/      # Reusable widgets (password prompt)
└── cleansys-gui/            # Iced desktop GUI (binary: cleansys-gui)
    └── src/
        ├── state.rs          # Application state
        ├── update.rs         # Elm-style update logic
        ├── view.rs           # Rendering (tabs, cards, activity log)
        └── icons.rs          # Bootstrap icon glyph constants

Adding a new cleaner is a one-line addition to the platform-appropriate get_cleaners()/linux_cleaners()/macos_cleaners()/windows_cleaners() list in cleaners/user_cleaners.rs or cleaners/system_cleaners.rs, via the local cleaner! macro rather than a full CleanerInfo { .. } struct literal:

cleaner!(
    "My New Cleaner",
    "Short description shown in the TUI/GUI",
    clean_my_new_thing,
    requires_root: false   // omit this argument in user_cleaners.rs
),

Every privileged (requires_root: true) cleaner should perform its actual removal via the shared execute_with_sudo/run_sudo_step helpers in system_cleaners.rs rather than shelling out directly — run_sudo_step turns a failed command into a real Err (visible in the TUI/GUI as ❌) instead of a silently-swallowed "nothing was cleaned".

🖥️ Platform Support

Cleaners are real and platform-native on every OS — not just Linux paths that happen to compile elsewhere. Each cleaner resolves OS-appropriate locations (see cleansys-core::cleaners::platform) and measures real freed bytes (no estimates).

Platform	cleansys (TUI/CLI)	cleansys-gui	User cleaners	System cleaners
Linux (x86_64, aarch64)	✅	✅	Firefox/Chrome/Chromium caches, ~/.cache, thumbnails, /tmp, pip/npm/cargo caches, XDG Trash	apt/pacman/dnf caches, rotated logs + journald vacuum, /var/cache, old kernels, crash reports (root required)
macOS (Intel + Apple Silicon)	✅	✅	Firefox/Chrome/Safari caches, ~/Library/Caches, QuickLook thumbnails, $TMPDIR, pip/npm/cargo caches, ~/.Trash	Homebrew cache (not root — brew refuses to run as root), Xcode DerivedData, unavailable Simulator caches, rotated system logs, diagnostic/crash reports (root required)
Windows (x86_64)	✅	✅	Chrome/Edge/Firefox caches, Windows INetCache/CrashDumps, thumbnail cache, %TEMP%, pip/npm/cargo caches	Windows Update download cache, C:\Windows\Temp (Administrator), Recycle Bin (via Shell32, no Administrator needed for your own bin)

Windowing / desktop-environment support for cleansys-gui (via Iced/winit):

• Linux: X11 and Wayland (both enabled by default)
• macOS: native Cocoa/AppKit windowing (Intel + Apple Silicon, universal binary in releases)
• Windows: native Win32 windowing

The terminal UI (cleansys, via Ratatui/Crossterm) works in any terminal emulator on any of the three platforms.

See Releases for pre-built binaries: Linux .deb/.rpm/AppImage, Windows NSIS installer, and a universal macOS .dmg.

🧪 Testing

Run the test suite:

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test module
cargo test --test integration_tests

🤖 Automated Maintenance

A nightly Gitea Actions job (.gitea/workflows/deps-update.yml) upgrades every workspace dependency pin, runs the full quality gate (fmt, clippy, test), and— if anything actually changed—automatically cuts a new patch release: it commits the dependency bump, then bumps the workspace version (X.Y.Z → X.Y.Z+1), regenerates CHANGELOG.md, and pushes the tag directly to main. No PR, no manual approval — pushing the tag triggers the normal Release workflow (build, package, crates.io publish, AUR update). If the quality gate fails at any point the job simply stops; nothing broken is ever released.

Run the same flow locally with just auto-patch-release.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Repository
• Crates.io
• Documentation

🎥 Demo Creation

CleanSys uses VHS to create terminal session recordings. The demo tapes showcase:

• demo.tape: Main demo showing both user and system cleaners
• userland-cleaners.tape: Detailed walkthrough of user-level cleaning (no root required)
• system-cleaners.tape: Detailed walkthrough of system-level cleaning (requires authentication)

Generating Demos

# Install VHS (requires Go)
# See: https://github.com/charmbracelet/vhs#installation

# Generate main demo
just vhs

# Generate userland cleaners demo
just vhs-userland

# Generate system cleaners demo
just vhs-system

# Generate all demos
just vhs-all

# Clean generated demos
just vhs-clean

All generated GIF files are output to demo/target/ and are git-ignored.

🗺️ Roadmap / Ideas

Things that would be natural next steps for the project (contributions welcome!):

• Scheduled/background cleaning — a small daemon or OS-native scheduler (systemd timer / launchd / Task Scheduler) integration to auto-clean on a cadence.
• Pluggable/custom cleaners — user-defined cleaner rules via a TOML config (glob patterns + safety checks), loaded by cleansys-core and shared by both front-ends.
• GUI disk-usage chart — port the TUI's pie/bar chart (tui-piechart) to an Iced Canvas widget in cleansys-gui for visual parity.
• Light/dark auto-detection for the GUI theme (follow OS preference by default, falling back to the manual picker).
• Localization (i18n) for both UIs.
• JSON output for cleansys list / cleansys user --yes etc., to make the CLI scriptable.
• AUR / winget / Homebrew formulae for easier installation (AUR PKGBUILD scaffold already included under packaging/aur/).
• TUI selection persistence — the GUI already remembers checked cleaners across restarts (~/.config/cleansys/settings.json); the TUI could opt into the same tui-settings.json file.
• Branded icon/artwork — packaging/windows/cleansys.ico and packaging/macos/cleansys.icns currently fall back to a placeholder/no icon; real artwork would polish the installers/DMG.

🙏 Acknowledgments

• Ratatui - Terminal UI framework
• tui-checkbox - Checkbox widget library
• tui-spinner - Animated loading spinner widget
• tui-piechart - Pie chart visualization widget
• Crossterm - Cross-platform terminal manipulation
• Iced - Cross-platform Rust GUI framework powering cleansys-gui
• iced_fonts - Bootstrap icon font for the GUI
• VHS - Terminal session recorder for creating demos

---

Note: Always review what will be cleaned before running system-level operations. While CleanSys is designed to be safe, it's good practice to understand what's being removed from your system.