🫰 Thanos

"Perfectly balanced, as all things should be."

A Python CLI tool that randomly eliminates a configurable percentage of files in a directory with a snap (default: 50%). Inspired by Marvel's Thanos and his infamous snap.

⚠️ Warning

This tool permanently deletes files! Use --dry-run first to preview what would be deleted. Deleted files cannot be recovered. Use at your own risk!

✨ Features

• 🗑️ Trash Mode: Optionally move files to the system trash/recycle bin instead of permanent deletion.
• ⚖️ Weighted Selection: Configure probabilities based on file age, size, or extension.
• 🛡️ Smart Protections: Automatically protects .git, node_modules, venv, and system files.
• 🚫 Custom Ignore: Support for .thanosignore using gitignore syntax.
• 🎲 Reproducibility: Use seeds to ensure the exact same files are selected every time.
• 📁 Recursive Support: Optionally include files in subdirectories.

📦 Installation

Using uv (recommended)

uv add thanos-cli
uv pip install thanos-cli   # <- if you don't have pyproject.toml

Using pipx (recommended for CLI use)

pipx install thanos-cli

Installs thanos as an isolated CLI tool available system-wide without polluting your global Python environment.

Using pip

pip install thanos-cli

🚀 Quick Start

1. Initialize Configuration

Create default .thanosignore and .thanosrc.json files in your project:

thanos init

2. Preview the Snap

Always start with a dry run to see the "dead" files without deleting them:

thanos snap --dry-run

3. Execute

When you are ready to restore balance:

# Permanent deletion (Standard Snap)
thanos snap

# Safer Snap (Move to Trash)
thanos snap --trash

⚙️ Configuration

Thanos supports advanced configuration to control the chaos.

.thanosignore

Protect specific files or folders from being snapped (gitignore syntax):

# Protect specific folders
src/
important_docs/
!debug.log

.thanosrc.json

Define weights (0.0 to 1.0) to make specific files more or less likely to be eliminated.

• 0.0: Never eliminate
• 0.5: Neutral (Default)
• 1.0: Always eliminate

Supported weight types:

• by_extension — e.g., target .tmp or .log files
• by_age_days — e.g., target files older than 30+ days
• by_size_mb — e.g., target files larger than 100+ MB

See docs/configuration.md for the full schema.

📖 Commands

The CLI structure:

• thanos init — Generate configuration files.
• thanos snap [DIRECTORY] [OPTIONS] — Main command to eliminate files.

Options:

• -t, --trash — Move files to system trash instead of permanent deletion.
• -r, --recursive — Include subdirectories
• -d, --dry-run — Preview without deleting
• -p, --percent <INT> — Percentage of files to eliminate (default: 50, range: 1–100)
• --seed <INT> — Set seed for reproducibility
• --no-protect — Disable protections (dangerous)

For detailed usage, see docs/usage.md.

📝 License

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

🤔 FAQ

Q: Can I recover deleted files? A: If you use the --trash flag, YES, you can restore them from your system's Recycle Bin/Trash. If you run the standard command without that flag, files are permanently deleted.

Q: How are files selected? A: Randomly, but you can bias the selection using weights in .thanosrc.json.

Q: What is protected by default? A: .git, .svn, node_modules, venv, __pycache__, .env, and more.

Q: What if I have an odd number of files? A: The count is calculated as int(total * percent / 100), so with 11 files at the default 50%, 5 will be deleted and 6 will remain. Use --percent to adjust.

🙏 Acknowledgments

• Inspired by the Marvel Cinematic Universe

---

Remember: With great power comes great responsibility. Use Thanos wisely! 🫰