Show HN: AI-rganize: Just another file/folder organizing AI terminal tool

13 hours ago 1

An intelligent file organization tool that uses AI to automatically categorize and organize your files. Works on macOS, Linux (Ubuntu, etc.), and Windows.

Name was inspired by the music I was listening to when this idea popped in my head, the music is Organize by Asake

🤖 AI-Powered Categorization: Uses OpenAI's GPT to intelligently categorize files based on content and metadata
📂 Multiple Directory Support: Organizes common directories (Documents, Desktop, Downloads, etc.)
🔒 Cross-Platform: Works on macOS, Linux (Ubuntu, etc.), and Windows
🔒 Permission Handling: Properly handles file access permissions across platforms
💾 Backup System: Creates automatic backups before moving files
🎯 Smart Organization: Groups files into logical categories (documents, images, videos, audio, etc.)
🖥️ Terminal Interface: Clean, user-friendly command-line interface
🔍 Dry Run Mode: Preview organization plan before making changes

Quick Start with uv (Recommended)

Why uv? uv provides fast, reliable Python project management with automatic virtual environment creation, dependency resolution, and lockfile management. It's significantly faster than pip and handles all the complexity of Python environments for you.

First, install uv and ffmpeg:

macOS:

Linux:

# Install uv curl -LsSf https://astral.sh/uv/install.sh | sh # Install ffmpeg sudo apt update && sudo apt install ffmpeg # Ubuntu/Debian # or sudo yum install ffmpeg # CentOS/RHEL

Windows:

# Install uv powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Install ffmpeg choco install ffmpeg # or download from https://ffmpeg.org/download.html

Alternative (PyPI):

pip install uv # Then install ffmpeg separately for your platform

For more installation options, see the official uv installation guide.

Then set up ai-rganize:

# 1. Clone the repository git clone https://github.com/yourusername/ai-rganize.git cd ai-rganize # 2. Create virtual environment with uv uv venv # 3. Activate the virtual environment source .venv/bin/activate # On macOS/Linux # or .venv\Scripts\activate # On Windows # 4. Install dependencies and package uv pip install -r requirements.txt uv pip install -e . # 5. Set up API key export OPENAI_API_KEY="your_api_key_here" # 6. Test with dry run ai-rganize --dry-run

What uv does for you:

🚀 Automatic virtual environment creation (.venv/ directory)
📦 Dependency resolution and installation from pyproject.toml
🔒 Lockfile management (uv.lock) for reproducible builds
⚡ Fast package installation (10-100x faster than pip)
🛠️ Project management with uv sync, uv add, uv remove
🐍 Python version management with uv python install

Install dependencies:

pip install -r requirements.txt
Get OpenAI API Key:
- Visit OpenAI Platform
- Create a new API key
- Add it to your environment or .env file
Set up permissions:
- macOS: System Preferences > Security & Privacy > Privacy
- Linux: Check file ownership and permissions
- Windows: Run as Administrator if needed

Basic commands:

ai-rganize # Organize all common directories ai-rganize --dry-run # Dry run (preview without moving files) ai-rganize --directory ~/Documents # Organize specific directory ai-rganize --max-file-size 5 # Limit AI analysis to files smaller than 5MB ai-rganize --ai-limit 20 --max-file-size 15 # Limit AI analysis to 20 files and files smaller than 15MB

Alternative: Using uv run (no activation needed):

uv run ai-rganize --dry-run uv run ai-rganize --directory ~/Documents

Model selection and cost control:

# Use different OpenAI models ai-rganize --openai-model gpt-4o-mini --dry-run # Cheaper, still intelligent ai-rganize --openai-model gpt-3.5-turbo --dry-run # Cheapest option ai-rganize --openai-model gpt-4 --dry-run # Most expensive, highest quality # LLM provider selection (future-ready) ai-rganize --llm-provider openai --dry-run # OpenAI (default, currently supported) # ai-rganize --llm-provider claude --dry-run # Claude (coming soon) # ai-rganize --llm-provider gemini --dry-run # Gemini (coming soon) # Control batch processing and costs ai-rganize --batch-size 3 --max-cost 0.5 --dry-run # Smaller batches, lower cost limit ai-rganize --ai-limit 100 --batch-size 10 --dry-run # Process more files in larger batches

Project management with uv:

uv sync # Install/update dependencies uv lock --upgrade # Update lock file uv add package-name # Add new dependency uv remove package-name # Remove dependency uv tree # View dependency tree

--api-key: OpenAI API key (or set OPENAI_API_KEY env var)
--directory, -d: Specific directory to organize
--dry-run: Show organization plan without moving files
--backup/--no-backup: Create backup before organizing (default: backup)
--ai-limit: Maximum number of files to analyze with AI (default: 50)
--max-file-size: Maximum file size in MB for AI analysis (default: 10)
--no-ai: Disable AI categorization, use only rule-based

export OPENAI_API_KEY="your_api_key_here"

Or create a .env file:

OPENAI_API_KEY=your_api_key_here

File Scanning: Scans target directories for files
AI Analysis: Uses OpenAI GPT to analyze file content and metadata
Categorization: Groups files into logical categories:
- 📄 Documents (PDFs, Word docs, text files)
- 🖼️ Images (photos, graphics, screenshots)
- 🎬 Videos (movie files, recordings)
- 🎵 Audio (music, podcasts, recordings)
- 📦 Archives (zip files, compressed files)
- 💻 Code (programming files)
- 📊 Spreadsheets (Excel, CSV files)
- 📽️ Presentations (PowerPoint, Keynote)
- 📁 Other (miscellaneous files)
Organization: Moves files to appropriate category folders
Logging: Records all changes for reference

✅ Automatic Backups: Creates timestamped backups before any changes
✅ Dry Run Mode: Preview changes before executing
✅ Permission Checks: Verifies access to directories
✅ Duplicate Handling: Prevents overwriting existing files
✅ Error Handling: Graceful handling of permission errors
✅ Logging: Complete audit trail of all changes

The tool organizes files into these categories:

Category File Types Examples

Documents	PDF, DOC, TXT, RTF	Reports, letters, manuals
Images	JPG, PNG, GIF, HEIC	Photos, screenshots, graphics
Videos	MP4, MOV, AVI, MKV	Movies, recordings, clips
Audio	MP3, WAV, FLAC, M4A	Music, podcasts, recordings
Archives	ZIP, RAR, 7Z, TAR	Compressed files, backups
Code	PY, JS, HTML, CSS	Programming files, scripts
Spreadsheets	XLS, CSV, NUMBERS	Data files, reports
Presentations	PPT, KEY	Slides, presentations

ai-rganize/ ├── __init__.py # Package initialization ├── core.py # Main ai-rganize class ├── cli.py # Command-line interface ├── permissions.py # Permission handling ├── permissions_cli.py # Permission setup CLI └── utils.py # Utility functions

Development & Contributing

Setup for development:

# Clone and setup git clone https://github.com/adefemi171/ai-rganize.git cd ai-rganize uv venv source .venv/bin/activate # On macOS/Linux # or .venv\Scripts\activate # On Windows uv pip install -r requirements.txt uv pip install -e .

Development commands:

ai-rganize --help # Test the tool ai-rganize --dry-run # Test with dry run uv sync # Install/update dependencies uv lock --upgrade # Update lock file

Contributing:

Fork the repository
Create a feature branch
Make your changes
Test: ai-rganize --dry-run
Submit a pull request

# Check permissions ai-rganize-permissions # If you get permission errors, try organizing specific directories: ai-rganize --directory ~/Documents

# Make sure your API key is set: export OPENAI_API_KEY="your_key_here" # Or check your .env file

Video/Audio Analysis Issues

# If video/audio analysis fails, check ffmpeg: ffmpeg -version # Test with a small file first: ai-rganize --directory ~/Desktop --ai-limit 1 --dry-run --verbose

The tool automatically skips files larger than 10MB for AI analysis to avoid high API costs. These files are categorized using rule-based methods.

Backups are stored in ~/.ai-rganize_backup/
Each backup is timestamped
Organization logs are stored in ~/.ai-rganize_log.json

Python 3.7+
OpenAI API key
Internet connection (for AI analysis)

openai: AI categorization
click: Command-line interface
rich: Beautiful terminal output
Pillow: Image file analysis

MIT License - feel free to use and modify!

Contributions welcome! Please feel free to submit issues and pull requests.

This tool moves and organizes your files. Always:

Test with --dry-run first
Keep backups enabled
Review the organization plan before proceeding
Use at your own risk

The AI categorization is based on file content analysis and may not be 100% accurate. Always review the results before proceeding with large-scale organization.

Read Entire Article