Smart file cleanup for your home directory — safe by default (dry-run mode).
Move, quarantine, or summarize large / old files with confidence.

Home Cleanup is a command-line tool that scans your filesystem and identifies large or old files for potential cleanup.
By default, it runs in dry-run mode — simulating what would happen before any files are actually moved.

When you’re confident, just add the --really flag to perform the moves.

⚙️ Ideal for developers, sysadmins, or power users who want to declutter large directories safely.

git clone https://github.com/ContentGardeningStudio/home-cleanup
cd home-cleanup
python -m venv .venv
source .venv/bin/activate  # or .\.venv\Scripts\activate on Windows
pip install -e .
python -m clean_home --help

python -m clean_home --path ~/Downloads --older-than-days 90 --min-size-mb 50

clean_home/
 ┣ 📄 __main__.py
 ┣ 📄 scanner.py
 ┣ 📄 filters.py
 ┣ 📄 summarize.py
 ┣ 📄 actions.py
 ┗ 📄 logging_conf.py

Found 12 candidates (1.2 GB total)
  /Users/alex/Downloads/old_backup.zip (600 MB, 180 days old)
  /Users/alex/Movies/recording.mov (420 MB, 270 days old)
Dry-run only — no files were moved.

{
  "candidates": 12,
  "total_size_mb": 1200,
  "files": [
    {"path": "...", "size_mb": 600, "days_old": 180}
  ]
}

• Practice Python’s standard libs: os, pathlib, argparse, logging
• Separate pure logic from side effects
• Implement safe dry-run vs real mode

Pull requests and ideas welcome!

1. Fork the repo
2. Create a feature branch (git checkout -b feature/new-filter)
3. Commit your changes
4. Open a PR 🚀

We help MVP builders ship better. Join our Skool community for feedback, technical guidance, and deep-dive discussions to level up your project.

👉 Join here: https://www.skool.com/onboard-or-join-a-tech-team

Licensed under the MIT License.
© 2025 Content Gardening Studio — small, focused tools for modern dev workflows.