cleanupx 2.0.4

File processing and organization tool — smart categorization, batch rename, duplicate detection, and directory cleanup

cleanupx

File processing and organization tool with smart categorization, batch rename, duplicate detection, and directory cleanup. Optionally generates image alt-text via vision models.

Install

pip install cleanupx

Set XAI_API_KEY in your environment to enable vision features like alt text generation (optional).

Usage

# Organize files by type
cleanupx organize --dir ~/Downloads

# Find and handle duplicates
cleanupx deduplicate --dir ~/Projects

# Generate alt text for images (requires XAI_API_KEY)
cleanupx images --dir ./photos

# Run all processing steps
cleanupx comprehensive --dir ./documents

# Scramble filenames for privacy (reversible)
cleanupx scramble --dir ./sensitive_data

What It Does

• Deduplication: SHA256 hash-based duplicate detection
• File Organization: categorize by type (images, code, documents, archives)
• Image Alt Text: generate accessibility descriptions via vision models
• Code Extraction: pull and analyze code snippets from files
• Filename Scrambling: randomize names for privacy, with undo log
• PDF/DOCX Support: process documents alongside plain text

Supported File Types

Images (jpg, png, gif, webp, bmp, tiff), code (py, js, html, css, md, json, yaml), documents (pdf, doc, docx, rtf, pptx), archives (zip, tar, gz, rar).

Structure

cleanupx/
├── cleanupx.py           # CLI entry point
├── cleanupx_core/        # Core processing modules
│   ├── api/              # XAI integration
│   ├── processors/       # File type handlers
│   └── utils/            # Common utilities
└── storage/              # Experimental/archived code

Configuration

XAI_API_KEY=your-key      # Required for vision features (alt text generation)
CLEANUP_OUTPUT_DIR=./out  # Custom output directory
CLEANUP_LOG_LEVEL=INFO    # Logging verbosity

Dependencies

Core: requests, rich, inquirer, pillow, PyPDF2, python-docx. Optional: openai, PyHEIF, rarfile.

License

MIT. Luke Steuber ([e-mail])