NoEntropy 🗂️

AI-powered file organizer that intelligently sorts your messy Downloads folder using Google Gemini API

About

NoEntropy is a smart command-line tool that organizes your cluttered Downloads folder automatically. It uses Google's Gemini AI to analyze files, understand their content, and categorize them into organized folder structures. Say goodbye to manually sorting through hundreds of downloads!

Features

• 🧠 AI-Powered Categorization - Uses Google Gemini API for intelligent file sorting
• 🎨 Custom Categories - Define your own categories for personalized organization
• 📁 Automatic Sub-Folders - Creates relevant sub-folders based on file content analysis
• 💨 Smart Caching - Minimizes API calls with metadata-based caching (7-day expiry)
• ⚡ Concurrent Processing - Parallel file inspection with configurable limits
• 👀 Dry-Run Mode - Preview changes without moving any files
• 📝 Text File Support - Inspects 30+ text formats for better categorization
• ✅ Interactive Confirmation - Review organization plan before execution
• ↩️ Undo Support - Revert file organization changes if needed

Quick Start

Installation

Download Pre-built Binary

Download the latest release for your operating system from releases:

OS	Download
Linux x86_64	noentropy-x86_64-unknown-linux-gnu.tar.gz
macOS x86_64	noentropy-x86_64-apple-darwin.tar.gz
macOS arm64	noentropy-aarch64-apple-darwin.tar.gz
Windows x86_64	noentropy-x86_64-pc-windows-msvc.zip

Linux/macOS:

# Download and extract
curl -LO https://github.com/glitchySid/noentropy/releases/latest/download/noentropy-x86_64-unknown-linux-gnu.tar.gz
tar -xzf noentropy-x86_64-unknown-linux-gnu.tar.gz

# Add to PATH (user-level)
mkdir -p ~/.local/bin
mv noentropy ~/.local/bin/
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc

# Verify
noentropy --help

Windows:

# Download and extract
Invoke-WebRequest -Uri "https://github.com/glitchySid/noentropy/releases/latest/download/noentropy-x86_64-pc-windows-msvc.zip" -OutFile "noentropy.zip"
Expand-Archive -Path "noentropy.zip" -DestinationPath "noentropy"

# Add to PATH (User-level)
$env:PATH += ";$env:USERPROFILE\AppData\Local\NoEntropy"

# Or add via System Properties:
# Win + R → sysdm.cpl → Environment Variables → Edit PATH

See the Installation Guide for detailed instructions.

Build from Source

git clone https://github.com/glitchySid/noentropy.git
cd noentropy
cargo build --release
./target/release/noentropy

First Run

On first run, NoEntropy will guide you through an interactive setup to configure your API key and download folder. That's it!

Basic Usage

# Organize your downloads folder
./noentropy

# Organize a specific directory (current directory)
./noentropy .

# Organize a specific directory (absolute path)
./noentropy /path/to/folder

# Preview changes without moving files
./noentropy --dry-run

# Preview organization of current directory
./noentropy . --dry-run

# Undo the last organization
./noentropy --undo

Documentation

Comprehensive documentation is available in the docs/ directory:

• Installation Guide - Detailed installation instructions and setup
• Configuration Guide - Configure API key, folders, and custom categories
• Usage Guide - Command-line options and usage examples
• How It Works - Architecture, caching, and internal processes
• Troubleshooting - Common issues and solutions
• Development Guide - Project structure and development setup
• Contributing Guide - How to contribute to NoEntropy

Example Output

$ ./noentropy

Found 47 files. Asking Gemini to organize...
Gemini Plan received! Performing deep inspection...
Deep inspection complete!

--- EXECUTION PLAN ---
Plan: image1.png -> Images/
Plan: document.pdf -> Documents/
Plan: notes.txt -> Documents/Notes/
Plan: config.yaml -> Code/Config/
Plan: script.py -> Code/Scripts/
...

Do you want to apply these changes? [y/N]: y

--- MOVING FILES ---
Moved: image1.png -> Images/
Moved: document.pdf -> Documents/
Moved: notes.txt -> Documents/Notes/
...

Organization Complete!
Files moved: 47, Errors: 0
Done!

Custom Path Support

NoEntropy now supports organizing any directory, not just your configured Downloads folder!

Organize Any Directory

# Organize current directory
./noentropy .

# Organize specific folder
./noentropy /path/to/folder

# Organize with relative path
./noentropy ./subfolder

Features

• Path Validation: Ensures the directory exists and is accessible
• Path Normalization: Resolves ., .., and symlinks for consistency
• Full Compatibility: Works with all existing options (--dry-run, --recursive, etc.)
• Security: Prevents path traversal attacks and invalid paths

Use Cases

• Quickly organize project directories
• Clean up specific folders without changing configuration
• Test organization on different directories
• Organize documents, downloads, or any file collection

# Preview organization of current directory
./noentropy . --dry-run

# Organize project folder recursively
./noentropy ./my-project --recursive

# Undo organization in specific directory
./noentropy /path/to/folder --undo

Use Cases

• 📂 Organize a messy Downloads folder
• 🤖 Auto-categorize downloaded files by type and content
• 🔍 Smart sub-folder creation based on file content
• 🚀 Batch file organization without manual effort
• 💾 Reduce clutter and improve file system organization

Key Features Explained

Custom Categories

Define your own categories instead of using defaults:

# config.toml
categories = ["Work", "Personal", "School", "Projects", "Bills", "Media", "Misc"]

Perfect for organizing files based on your specific workflow. See the Configuration Guide for examples.

Smart Caching

NoEntropy caches API responses for 7 days to minimize costs and improve performance. Files are only re-analyzed if they change (based on size and modification time).

Undo Functionality

Made a mistake? Easily undo the last organization:

./noentropy --undo

All file moves are tracked for 30 days with full conflict detection and safety features.

Requirements

• Rust 2024 Edition or later (if building from source)
• Google Gemini API Key - Get one at https://ai.google.dev/

Command-Line Options

Option	Short	Description
[PATH]	-	Path to organize (defaults to configured download folder)
--dry-run	-d	Preview changes without moving files
--max-concurrent	-m	Maximum concurrent API requests (default: 5)
--recursive	-	Recursively search files in subdirectories
--undo	-	Undo the last file organization
--change-key	-	Change Gemini API key
--help	-h	Show help message

See the Usage Guide for detailed examples and workflows.

Project Structure

noentropy/
├── docs/               # Comprehensive documentation
├── src/
│   ├── cli/            # Command-line interface
│   ├── files/          # File operations and detection
│   ├── gemini/         # AI integration
│   ├── models/         # Data structures
│   ├── settings/       # Configuration management
│   └── storage/        # Caching and undo log
├── Cargo.toml
└── README.md

See the Development Guide for detailed architecture information.

Contributing

Contributions are welcome! Please see our Contributing Guide for:

• How to report bugs
• How to suggest features
• Development setup
• Code standards
• Pull request process

Future Enhancements

• Custom Categories
• Recursive Mode
• Undo Functionality
• Custom AI Models (OpenAI, Claude, etc.)
• GUI Version
• Watch Mode

License

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

Acknowledgments

• Built with Rust
• Powered by Google Gemini API
• Inspired by the endless struggle to keep Downloads folders organized

Support

• Check the Troubleshooting Guide for common issues
• Browse GitHub Issues for known problems
• Create a new issue for bugs or feature requests
• Star this repository if you find it useful!

---

Made with ❤️ by the NoEntropy team