Skip to content

README.md

Latest commit

 

History

History
300 lines (226 loc) · 14.2 KB

README.md

File metadata and controls

300 lines (226 loc) · 14.2 KB
Raw
haruru desktop icon

haruru

Fast, fun, cross-platform disk usage analyzer with an animated sunburst & AI storage assistant.

License: AGPL-3.0 Rust Platform Latest Release

haruru is an open-source, high-performance disk usage analyzer and cleanup application built in Rust with egui and eframe. It empowers you to inspect your storage through interactive animated radial charts and treemaps, safely clean up junk and stale developer caches, find duplicate files, scan remote SSH servers and cloud buckets, and consult an integrated AI storage advisor.

Note

Status: Active development. Review files before deleting them and keep backups of important data. AI suggestions and cleanup categories provide interactive previews before any removal takes place.

📥 Download

Prebuilt binaries and release packages for all supported platforms are published on the GitHub Releases page:

👉 Download Latest Release
📦 View All Releases

Platform Package / Format Description
Windows haruru-windows-x86_64.msi Windows Installer (MSI): Standard Windows setup wizard with Start Menu shortcut, Desktop icon, and Add/Remove Programs support
Windows haruru-windows-x86_64.exe Direct Standalone Executable: Direct download (no unzipping needed). Double-click to run immediately
Windows haruru-windows-x86_64.zip Portable Archive: ZIP containing haruru.exe for portable flash drive usage
macOS haruru-macos-universal.zip Universal App Bundle (haruru.app): Supports Apple Silicon (M1/M2/M3/M4) and Intel
Linux haruru-linux-x86_64.tar.gz Linux 64-bit Tarball: Standalone binary with .desktop launcher and high-resolution icons
Linux Flatpak Sandboxed package built with the included Flatpak manifest
CLI / Server haruru (Headless) Ultra-compact headless agent binary (--no-default-features) for Linux servers and remote SSH scanning

✨ Features Explained

1. 🎯 Interactive Animated Sunburst View

  • Multi-Level Radial Visualization: Visualizes directory hierarchies as concentric colored rings where arc length directly represents folder size.
  • Fluid Drill-Down Navigation: Click any slice to smoothly zoom into that directory and explore nested storage consumers.
  • Slice Hover Insights: Hovering over any slice provides instant details including relative path, total size, percentage of parent, and file counts.
  • History Breadcrumbs: Easily backtrack and jump between parent and child directories with breadcrumb buttons and history arrows.

2. 🗺️ Squarified Treemap View

  • Proportional Space Filling: An alternative hierarchical layout based on the squarified treemap algorithm that packs directories into rectangles.
  • Instant Storage Hog Detection: Visually identify disproportionately large single files or folder clusters at a single glance.
  • Interactive Deep-Dive: Double-click or click through nested boxes to explore deeper layers.

3. 🧹 Smart Cleanup Dashboard

  • 8 Dedicated Cleanup Categories:
    • System & Application Junk: Cache files, temporary runtime data, and application residue.
    • Downloads: Stale downloaded files, disk images, and installers older than your chosen threshold.
    • Large Untouched Files: Space-consuming files that have not been modified or accessed in a long time.
    • Old Screenshots: Accumulated desktop captures and screen recordings.
    • Inactive Applications: Discovered applications that have not been launched recently.
    • Installers & Disk Images: Forgotten .iso, .dmg, .pkg, .deb, .rpm, .appimage, and .exe installers.
    • Archive Bundles: Redundant .zip, .tar.gz, .7z, and .rar archives.
    • Trash / Recycle Bin: Items waiting in the operating system trash that can be safely purged.
  • Live Disk Capacity Gauge: Shows overall volume size, used space, and free capacity in real time.
  • Batch Selection & Dry-Run Preview: Review item details, open their enclosing directories, and select/unselect items prior to deletion.

4. 🔍 High-Performance Duplicate File Finder

  • Multi-Stage Hashing Engine:
    • Stage 1: Quick file size grouping.
    • Stage 2: Fast partial sample hashing using xxh3 for rapid candidate filtering.
    • Stage 3: Full cryptographic verification (MD5 / SHA-1) ensuring 100% false-positive-free matching.
  • Grouped Cluster Inspection: Duplicates are visually clustered with the original file clearly demarcated.
  • Protected File Safeguards: Smart heuristics automatically protect libraries and system references so copies in active project dependencies or system locations are never accidentally marked for deletion.

5. 🤖 Context-Aware AI Storage Assistant

  • Multi-Provider Connectivity: Connect to your preferred AI model provider:
    • Google Gemini (Gemini 2.5 Flash, Gemini 2.5 Pro)
    • OpenAI (GPT-4o, GPT-4o-mini)
    • Anthropic Claude (Claude 3.5 Sonnet)
    • Groq & DeepSeek (via OpenAI-compatible API)
    • OpenRouter (Unified multi-model routing)
    • Local Ollama (Completely offline, local LLM inference without API keys)
  • Developer Artifact Investigation: Intelligently discovers oversized developer dependencies (node_modules, Rust target/, Python .venv, Docker caches, Gradle caches) and explains how to safely prune them.
  • Actionable Cleanup Plans: Generates interactive cleanup recommendations with buttons that jump directly into the relevant dashboard category.
  • Built-in Offline Heuristic Advisor: If no cloud API key is configured, an integrated rule-based storage advisor provides helpful suggestions instantly.

6. 🌐 Multi-Target & Remote Scanning

  • Local Drives & Partitions: Scan internal SSDs/HDDs, external USB drives, and mounted network volumes.
  • Remote SSH Servers: Connect via SSH to scan remote Linux servers. haruru deploys an ultra-fast, zero-dependency headless agent on-the-fly (haruru --agent) to index remote filesystems locally at native speed without transmitting sluggish file-by-file directory listings.
  • Cloud Storage via Rclone: Native integration with Rclone allows inspecting remote cloud storage, including Google Drive, Dropbox, Microsoft OneDrive, Amazon S3, Nextcloud, WebDAV, and more.
  • Built-In Demo Mode: Explore the full interface using sample filesystem structures without scanning personal drives.

7. 🛡️ Safety-First Deletion Engine

  • Native OS Trash Integration: Default deletion moves files to the native operating system Trash / Recycle Bin (trash crate) so deleted files can always be recovered.
  • Critical System Guards: Hardcoded protective rules strictly prevent deletion of system-critical paths (e.g. /, /bin, /usr, /etc, C:\Windows, C:\Program Files).
  • Permanent & Secure Erase Modes: Optional multi-pass overwrite wiping for sensitive data disposal.

8. 🎨 Adaptive Theming & Dynamic Desktop Icon

  • Theme Palette Options: Switch between Light, Dark, and sleek Monochrome themes.
  • Live System Appearance Detection:
    • Linux: Listens to desktop appearance portal events via gdbus without blocking the UI thread.
    • macOS: Responds to native appearance change notifications and dynamically updates the macOS Dock icon.
    • Windows: Automatically detects system light/dark theme preference changes.
  • Custom Visual Badges: SVG-based file type badges (documents, videos, installers, archives) in file cards.

9. 🌍 Multilingual Localization

  • Complete UI translation in 24 languages: English, Spanish, French, German, Italian, Portuguese, Russian, Ukrainian, Polish, Dutch, Turkish, Japanese, Chinese, Korean, Hindi, Bengali, Tamil, Telugu, Marathi, Urdu, Vietnamese, Thai, Indonesian, and Arabic.
  • Real-time language switching in Settings without restarting the app.

10. ⚡ Command-Line Interface (CLI)

  • Perform headless scans from terminal scripts or CI pipelines.
  • Supports depth limits, top-N heaviest file listings, and structured JSON output.
haruru scan ~/Projects --depth 2 --top 10
haruru scan ~/Downloads --json

🛠️ Building from Source

Ensure you have a stable Rust toolchain (edition 2021+) installed.

🐧 Building on Linux

Prerequisites (Debian / Ubuntu)

sudo apt-get update
sudo apt-get install -y libasound2-dev libxkbcommon-dev libwayland-dev libx11-dev

(On Fedora: sudo dnf install alsa-lib-devel libxkbcommon-devel wayland-devel libX11-devel)
(On Arch Linux: sudo pacman -S alsa-lib libxkbcommon wayland libx11)

Build & Run

# Run desktop GUI
cargo run --locked --release

# Build release binary
cargo build --locked --release

# Build headless agent / CLI only (no GUI dependencies)
cargo build --locked --release --no-default-features

The resulting binary is located at target/release/haruru.

🪟 Building for Windows

Native Windows Build (MSVC)

From PowerShell or Command Prompt on Windows:

cargo build --locked --release

The application icon (assets/icon/haruru.rc) is automatically embedded into target\release\haruru.exe.

Cross-Compiling for Windows from Linux

You can cross-compile from Linux using cargo-xwin:

cargo install cargo-xwin
rustup target add x86_64-pc-windows-msvc
cargo xwin build --locked --release --target x86_64-pc-windows-msvc

Portable Mode

On Windows and Linux, creating a folder named portable beside haruru.exe keeps all configuration, logs, and settings inside that directory instead of the system profile.

🍎 Building for macOS

Native Build

cargo build --locked --release

Universal Binary (Apple Silicon & Intel)

rustup target add aarch64-apple-darwin
rustup target add x86_64-apple-darwin

cargo build --locked --release --target aarch64-apple-darwin
cargo build --locked --release --target x86_64-apple-darwin

# Combine into a Universal binary
mkdir -p target/universal/release
lipo -create -output target/universal/release/haruru \
  target/aarch64-apple-darwin/release/haruru \
  target/x86_64-apple-darwin/release/haruru

Create macOS .app Bundle

  1. Create the bundle structure: 
    mkdir -p "haruru.app/Contents/MacOS"
mkdir -p "haruru.app/Contents/Resources"
cp target/release/haruru "haruru.app/Contents/MacOS/"
cp assets/icon/light/macos/icon.icns "haruru.app/Contents/Resources/haruru.icns"
  2. Add Info.plist (see .github/workflows/release.yml for template).

📦 Building with Flatpak (Linux)

A Flatpak manifest is provided in packaging/flatpak/io.github.javaadde.haruru.yaml.

Requirements

Install flatpak and flatpak-builder:

sudo apt-get install flatpak flatpak-builder
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install flathub org.freedesktop.Platform//24.08 org.freedesktop.Sdk//24.08 org.freedesktop.Sdk.Extension.rust-stable//24.08

Build & Install Flatpak

flatpak-builder --user --install --force-clean build-dir packaging/flatpak/io.github.javaadde.haruru.yaml

To run the installed Flatpak:

flatpak run io.github.javaadde.haruru

📦 Packaging Debian / Ubuntu .deb

Using cargo-deb:

cargo install cargo-deb
cargo deb

The generated .deb package will be placed in target/debian/.

🚀 Automated GitHub Actions Releases

This repository includes a multi-platform release workflow in .github/workflows/release.yml. When a version tag (e.g., v0.1.0) is pushed or triggered via workflow_dispatch, GitHub Actions automatically:

  1. Builds Linux x86_64 tarball with desktop launchers and icons.
  2. Builds Windows x86_64 zip with embedded icons.
  3. Builds macOS Universal (Apple Silicon + Intel) application bundle and zip.
  4. Publishes all artifacts to the GitHub Release.

To release a new version:

git tag v0.1.0
git push origin v0.1.0

⚙️ Configuration & Settings

  • Config Path: Settings are stored in the platform standard application configuration directory under haruru. Override this by setting HARURU_CONFIG_DIR.
  • Portable Folder: Placing a folder named portable next to the executable forces haruru to store all settings locally beside the binary.
  • Update Checks: Maintainers can compile in an official repository by setting the environment variable HARURU_GITHUB_REPO="owner/repo" during build time.
  • Privacy & Security: AI provider keys are stored securely in local app configuration and are never transmitted anywhere except directly to the configured AI API endpoints. Do not commit credentials to version control.

🧪 Development & Testing

Run the test suite with:

# Run all unit and integration tests
cargo test --locked

# Test headless / remote agent mode
cargo test --locked --no-default-features

# Verify release build
cargo build --locked

Tip

For faster local test cycles without compiling full dependency optimizations, pass:

CARGO_PROFILE_DEV_DEBUG=0 CARGO_PROFILE_TEST_DEBUG=0 cargo test --locked \
  --config 'profile.dev.package."*".opt-level=0' \
  --config 'profile.test.package."*".opt-level=0'

📄 License

Licensed under AGPL-3.0-only. Existing contributors' rights and the license terms remain in effect.