codecleaner

Version: 0.2.0

codecleaner is a conservative cleanup tool for development directories. It removes reproducible dependencies, caches, build artifacts, Python bytecode, and macOS Mach-O binaries while preserving Git metadata and configured preserved trees. It can also sanitize a tree for a target operating system and CPU architecture before or after migration.

Usage

Install locally:

python3 -m pip install .

Print the version:

codecleaner --version

Preview cleanup:

codecleaner ~/code --dry-run

Clean:

codecleaner ~/code

Preserve directories:

codecleaner ~/code \
  --preserve ~/code/floss \
  --preserve ~/code/experiments

Remember preserved directories:

codecleaner ~/code \
  --preserve ~/code/floss \
  --remember

Remembered paths are stored in:

~/.config/codecleaner/config.toml

Inspection Modes

Concise disk usage stats:

codecleaner ~/code --stats

Extended cleanup category stats:

codecleaner ~/code --stats --extended

Explain the reclaimable-space total:

codecleaner ~/code --stats --extended --explain-reclaimable

Show every reclaimable item instead of the default bounded list:

codecleaner ~/code --stats --extended --explain-reclaimable --all

Print scanner diagnostics:

codecleaner ~/code --stats --extended --verbose

Clean every item classified as reclaimable by extended stats:

codecleaner ~/code --clean-reclaimable

Walk through reclaimable items interactively:

codecleaner ~/code --clean-reclaimable --interactive

Safely rehearse interactive reclaimable cleanup:

codecleaner ~/code --clean-reclaimable --interactive --dry-run

Target-Platform Sanitization

Prepare a tree for a different platform before migration:

codecleaner ~/code \
  --sanitize-for linux-amd64 \
  --dry-run

Sanitize a copied tree for the machine running CodeCleaner:

codecleaner ~/code \
  --sanitize-for native \
  --dry-run

native resolves to the current host platform, such as linux-amd64 or macos-arm64. Use --sanitize as a shortcut for --sanitize-for native.

Supported initial targets:

linux-amd64
linux-arm64
macos-amd64
macos-arm64
native

Explain the exact sanitization items:

codecleaner ~/code \
  --sanitize-for linux-amd64 \
  --explain-sanitization

Walk through sanitization candidates interactively:

codecleaner ~/code \
  --sanitize-for linux-amd64 \
  --interactive

Largest repository/directory census:

codecleaner ~/code --census

Interactive census-based cleanup:

codecleaner ~/code --clean-by-census

During interactive cleanup:

y  delete
n  keep
s  skip subtree
q  quit

Use --include-preserved with --clean-by-census to allow scanning and deleting inside preserved directories.

Safety Notes

• Symlinks are not followed.
• .git directories are preserved during normal cleanup.
• Preserved paths are opaque during cleanup.
• --stats, --stats --extended, and --census are read-only.
• Mach-O files are detected by magic bytes, not by executable permissions.

Tests

Run the test suite:

python3 -m unittest discover -s tests -v

Packaging

Build and check local distributions:

python3 -m pip install build twine
python3 -m build
python3 -m twine check dist/*

Upload to PyPI when ready:

python3 -m twine upload dist/*

License

MIT License - Copyright (c) 2026 Antonio Ognio

Made with ❤️ from 🇵🇪. El Perú es clave 🔑.