A powerful Python CLI tool for analyzing and managing storage on macOS. Find what's using your disk space, safely clean up unnecessary files, and automate recurring cleanup tasks.
- Smart Storage Analysis: Identify reclaimable space with actionable recommendations
- Large File Discovery: Find files over configurable size thresholds
- Duplicate Detection: Content-based hashing to find duplicate files
- Developer Artifacts: Detect node_modules, .venv, build outputs, and caches
- File Type Breakdown: Analyze storage by file extension and category
- Directory Overview: See which directories consume the most space
- Age-Based Filtering: Delete files older than N days or not accessed recently
- Safety Ratings: Smart recommendations (safe/review/caution) for each item
- Dry-Run Mode: Preview deletions before committing
- Deletion Logging: Complete audit trail of all deletions
- Path Exclusions: Automatically protects system-critical directories
- Scheduled Cleanup: Native macOS launchd integration
- Flexible Scheduling: Set cleanup intervals, categories, and filters
- Automated Monitoring: Run cleanup commands automatically with full control
- Rich CLI: Beautiful terminal output with tables and progress bars
- Interactive TUI: Full-screen terminal interface (coming soon)
- Python 3.10 or higher
- macOS (uses macOS-specific paths and launchd)
# Clone the repository
git clone https://github.com/damienkilgannon/spaceman.git
cd spaceman
# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
# Install
pip install -e .
# Or install with development dependencies
pip install -e ".[dev]"spaceman --version
spaceman --help# Get a summary of reclaimable space
spaceman analyze
# See actual deletable items with safety ratings
spaceman analyze --detailed
# Analyze specific category
spaceman analyze caches
spaceman analyze developer# Clean specific category
spaceman clean caches
# Preview what would be deleted (dry-run)
spaceman clean downloads --dry-run
# Clean with filters
spaceman clean downloads --age 90 # Older than 90 days
spaceman clean large_files --last-accessed 180 # Not accessed in 6 months
spaceman clean developer --safety safe # Only safe items# Schedule weekly cache cleanup
spaceman schedule enable caches --interval 7
# Schedule monthly cleanup of old downloads
spaceman schedule enable downloads --age 90 --interval 30
# Check what's scheduled
spaceman schedule status
# Disable scheduling
spaceman schedule disable# See largest directories
spaceman overview
# Analyze by file type
spaceman typesAnalyze storage and show reclaimable space.
Categories: caches, downloads, large_files, duplicates, developer
Options:
--detailed, -d: Show list of deletable items instead of summary
Examples:
spaceman analyze # Summary of all categories
spaceman analyze --detailed # List all deletable items
spaceman analyze caches # Analyze only cachesClean storage by removing files and directories.
Options:
--dry-run: Preview deletions without actually deleting--safety, -s: Filter by safety rating (safe,review,caution)--age, -a N: Only delete items older than N days--last-accessed, -l N: Only delete items not accessed in N days
Examples:
spaceman clean caches
spaceman clean developer --safety safe
spaceman clean downloads --age 90 --dry-run
spaceman clean large_files --last-accessed 180Schedule automatic cleanup using launchd.
Subcommands:
enable [category]: Set up scheduled cleanupdisable: Stop scheduled cleanupstatus: Show current schedule
Enable Options:
--interval, -i N: Days between cleanup runs (default: 7)--safety, -s: Filter by safety rating--age, -a N: Only delete old items--last-accessed, -l N: Only delete unused items
Examples:
spaceman schedule enable caches --interval 7
spaceman schedule enable downloads --age 90 --interval 30
spaceman schedule status
spaceman schedule disableShow largest directories consuming space.
Options:
--limit, -n N: Number of directories to show (default: 20)
Analyze storage by file type.
Options:
--min-size, -s N: Minimum file size in MB (default: 10)--limit, -n N: Number of files to show (default: 50)
Manage configuration.
Subcommands:
show: Display current configurationedit: Open config file in editor
Configuration is stored in ~/.config/spaceman/config.toml:
[thresholds]
large_file_size_mb = 500 # Files larger than this are flagged
downloads_age_days = 30 # Downloads older than this are flagged
duplicate_min_size_mb = 10 # Only check duplicates for files this size+
[paths]
cache_locations = [
"~/Library/Caches",
"~/.cache",
]
exclude_patterns = [
"*.app/*", # Don't scan inside app bundles
"/System/*", # Protect system directories
"/Library/*",
]
downloads_path = "~/Downloads"
[analysis]
max_depth = 5 # Maximum directory recursion depth
follow_symlinks = false # Whether to follow symbolic links
[scheduling]
enabled = false
interval_days = 7
categories = ["caches", "downloads"] # Default categories for --auto mode
[safety]
require_confirmation = true # Prompt before deletion
log_deletions = true # Log all deletions
deletion_log_path = "~/.spaceman/deletions.log"Spaceman prioritizes data safety:
- ✅ Confirmation Required: All deletions require explicit confirmation
- ✅ Smart Recommendations: Items tagged as safe/review/caution
- ✅ Dry-Run Mode: Preview changes without actually deleting
- ✅ Deletion Logging: Complete audit trail in
~/.spaceman/deletions.log - ✅ Path Exclusions: System directories automatically protected
- ✅ Conservative Defaults: Safe thresholds prioritize data preservation
$ spaceman analyze
Storage Analysis Summary
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━┓
┃ Category ┃ Items ┃ Size ┃ Safe to Delete ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━┩
│ System caches │ 342 │ 2.3 GB │ 2.1 GB │
│ Old downloads │ 1205 │ 19.1 GB │ - │
│ Large files │ 45 │ 8.5 GB │ - │
│ Duplicates │ 15 │ 1.2 GB │ 1.0 GB │
│ Developer artifacts│ 8 dirs│ 5.4 GB │ 4.2 GB │
└────────────────────┴────────┴─────────┴────────────────┘
Total found: 36.5 GB
Safe to delete: 7.3 GB$ spaceman analyze --detailed
Deletable Items
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ Item ┃ Category ┃ Size ┃ Safety ┃ Recommendation ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ ~/project/node_modules │ Developer │ 2.1GB │ ✓ │ Can regenerate │
│ ~/Library/Caches/Chrome│ Caches │ 850MB │ ✓ │ Browser cache │
│ ~/Downloads/video.mp4 │ Downloads │ 1.2GB │ ? │ 45 days old │
│ ~/large-file.iso │ Large │ 4.5GB │ ? │ Manual review │
└────────────────────────┴───────────┴───────┴────────┴─────────────────┘
Summary:
Total items: 156 (36.5 GB)
✓ Safe to delete: 89 items (7.3 GB)
? Review required: 67 items (29.2 GB)$ spaceman clean downloads --age 90 --dry-run
Analyzing downloads...
Found 1205 items (19.1 GB)
Age filtering removed 1100 items, 105 items remain
[DRY RUN] Would delete 105 files (3.2 GB):
~/Downloads/old-presentation.pdf (45 MB) - 120 days old
~/Downloads/archive.zip (1.2 GB) - 95 days old
...$ spaceman schedule enable caches --interval 7
✓ Scheduled cleanup enabled
Command: spaceman clean caches
Interval: Every 7 days
Plist: ~/Library/LaunchAgents/com.spaceman.cleanup.plist
$ spaceman schedule status
Scheduling Status
Enabled: Yes
Command: spaceman clean caches
Interval: Every 7 days# Clone and install with dev dependencies
git clone https://github.com/damienkilgannon/spaceman.git
cd spaceman
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"# Run all tests
pytest
# Run with coverage
pytest --cov=spaceman
# Type checking
mypy --strict spaceman/# Format code
black .
isort .
# Lint
ruff check .spaceman/
├── spaceman/
│ ├── analyzers/ # Storage analysis modules
│ │ ├── cache.py # System cache analyzer
│ │ ├── developer.py # Dev artifacts analyzer
│ │ ├── directory.py # Directory size analyzer
│ │ ├── downloads.py # Downloads analyzer
│ │ ├── duplicates.py # Duplicate file detector
│ │ ├── file_type.py # File type analyzer
│ │ └── large_files.py # Large file finder
│ ├── cleaners/ # Cleanup operations
│ │ └── file_cleaner.py # Safe file deletion
│ ├── cli.py # Typer CLI commands
│ ├── config.py # Configuration management
│ ├── file_types.py # File categorization
│ ├── heuristics.py # Recommendation engine
│ ├── models.py # Data models
│ ├── scheduler.py # launchd integration
│ ├── tui.py # Textual TUI (coming soon)
│ └── utils.py # Utility functions
├── tests/ # Test suite
├── pyproject.toml # Project metadata
└── README.md
This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.
You are free to:
- Share: Copy and redistribute the material
- Adapt: Remix, transform, and build upon the material
Under these terms:
- Attribution: Give appropriate credit
- NonCommercial: Not for commercial use
- ShareAlike: Distribute derivatives under the same license
See the LICENSE file for full details.
Commercial Use: If you wish to use this software commercially, please contact the author for licensing options.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Quick checklist:
- Follow existing code style (Black formatting, type hints, Google-style docstrings)
- Add tests for new features
- Update documentation as needed
- Run
mypy --strictand tests before submitting
Built with excellent open source tools:
- Typer - Modern CLI framework
- Rich - Beautiful terminal formatting
- Textual - Terminal UI framework
- xxhash - Fast hashing for duplicate detection
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Additional analyzers (Docker, Bin, screenshots directory, applications (seperate from application & system caches), media files specific analyzer)
- Developer analyze - include project build caches and unused SDKs, pip caches, npm global packages
- Export reports (JSON, CSV, HTML)
- Background tasks and caching to get results faster