reclaimed is a cross-platform, ultra-lightweight, and surprisingly powerful command-line tool for analyzing disk usage — with special handling for iCloud storage on macOS.
Quickly find your largest files and directories with a beautiful, color-coded interface, and manage them through an interactive terminal UI.
Fully supports Linux, macOS, and Windows.
This README was crafted with AI assistance, and here's why that matters
As a solo developer building open source tools that may only ever serve my own needs, comprehensive documentation often wouldn't happen without AI help. Using agentic dev tools like Roo & Claude Code that understand the entire codebase, AI doesn't just regurgitate generic content - it extracts real implementation details and creates accurate, specific documentation.
In this case, Sonnet 4 took a pass & a human (me) verified them 6/28/25.
- 🚀 Legitimately Performant: Fast recursive directory scanning with ultra-efficient progress updates.
- Carefully tuned repaint frequency — optimized to avoid slowing results by even 5ms.
- Separate thread for the clock to keep real-time updates buttery smooth.
- ☁️ iCloud Aware: Detects and handles iCloud Drive symlink files vs local storage (macOS).
- 📊 Beautiful UI: Powered by Textualize/rich and Textualize/textual.
- Full keyboard navigation, mouse support, and customizable themes.
- 🖥️ Interactive Terminal UI: Browse, manage, and delete files/directories with ease.
- 🗑️ Safe Deletion: Remove large files and directories directly from the interface — with confirmation prompts.
- 💾 Export to JSON: Save scan results for further analysis or batch operations.
- ⚡ Real-Time Feedback: Live progress indicators and graceful handling of permission issues.
- 🛡️ Actual Privacy: 100% offline. No telemetry, no analytics, no tracking - can't even check for updates.
reclaimed_demo.mov
- Python 3.8+
- pip (Python package installer)
- (Optional but recommended) Use a virtual environment
uvx reclaimedpip install reclaimedbrew install taylorwilsdon/tap/reclaimedgit clone https://github.com/taylorwilsdon/reclaimed.git
cd reclaimed
pip install -e .reclaimed ~/Documents# Show more results
reclaimed ~/Documents --files 20 --dirs 15
# Skip specific directories during scanning
reclaimed ~/Documents --skip-dirs node_modules --skip-dirs __pycache__
# Save results to JSON
reclaimed ~/Documents --output results.json| Option | Description |
|---|---|
PATH |
Directory to scan (default: current directory) |
-f, --max-files N |
Number of largest files to show (default: 10) |
-d, --max-dirs N |
Number of largest directories to show (default: 10) |
-s, --skip-dirs DIR |
Additional directories to skip (can be specified multiple times) |
-o, --output FILE |
Save results to a JSON file |
-i, --interactive |
Launch the interactive Textual UI |
Interactive mode is on by default. Non-interactive mode (minimal output) can be forced with:
reclaimed ~/Documents --no-interactive| Key | Action | Key | Action | |
|---|---|---|---|---|
F |
Files view | Delete |
Remove item | |
D |
Directories view | R |
Refresh scan | |
S |
Sort items | Q |
Quit | |
H |
Hide directory | U |
Unhide all directories |
- Real-time progress indicator (files scanned, total size)
- Tables of largest files and directories
- iCloud vs local storage clearly indicated
- Summary of any access issues
- Tabbed interface: switch between Files and Directories
- Keyboard navigation (arrow keys) and mouse support
- Sort items by size, name, or path
- Delete files/directories with confirmation
- Refresh scan results
This project uses UV for building/publishing and Hatch for workflow management.
pip install -r requirements.txt
hatch shell# Run tests
hatch test
# Build distribution packages
uv build --sdist --wheel
# Create a new release
./release.sh
# Run interactively
python -m reclaimed /path/to/scanContributions are welcome!
Please see the Contributing Guide for details.
This project is licensed under the MIT License.
See the LICENSE file for full details.
Built with ❤️ for those who love clean disks and clean code.