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 (luke@dr.eamer.dev)

Metadata

Release files for cleanupx 2.0.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cleanupx 2.0.4
File	Size	Uploaded
cleanupx-2.0.4.tar.gz	80.5 kB	Apr 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cleanupx 2.0.4
File	Interpreter	ABI	Platform	Reset
cleanupx-2.0.4-py3-none-any.whl 85.0 kB Apr 22, 2026	Python 3	none	any	Details

Total release size: 165.4 kB

Release files / cleanupx-2.0.4.tar.gz

Download URL	cleanupx-2.0.4.tar.gz
Size	80.5 kB
Tags	Source
SHA-256 checksum How to use checksums	`9b7c732c5973ee1f0e292183ef49c5f4c26f75a4e273f37e826bc707686aad9e`
BLAKE2b-256 checksum How to use checksums	`451790ecf5b7fe640b747931e3e177073da069dc1a22d154e4d27e6cec4d308b`
Upload date	Apr 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.12`

Release files / cleanupx-2.0.4-py3-none-any.whl

Download URL	cleanupx-2.0.4-py3-none-any.whl
Size	85.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`29dc35cedd3e20f7a5b362231df358a1d0ebd7c87d0d5aa3a16429db9fe6a571`
BLAKE2b-256 checksum How to use checksums	`8deff6dc9cc7d7a5ce7318c99852d1a32d48f66d37cdb0f25277c2c91ef60eb5`
Upload date	Apr 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.10.12`