reclaimed ♻️
July 24, 2025 · View on GitHub
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.
A quick plug for AI-Enhanced Docs
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.
✨ Features
- 🚀 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.
https://github.com/user-attachments/assets/1aae04e7-3201-414d-a1e3-6ea5d55bd691
📦 Installation
Prerequisites
- Python 3.8+
- pip (Python package installer)
- (Optional but recommended) Use a virtual environment
uvx (fastest)
uvx reclaimed
Install via pip
pip install reclaimed
Install via Homebrew (macOS)
brew install taylorwilsdon/tap/reclaimed
Build from Source
git clone https://github.com/taylorwilsdon/reclaimed.git
cd reclaimed
pip install -e .
🚀 Usage
Basic
reclaimed ~/Documents
Advanced
# 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
Options
| 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
Interactive mode is on by default. Non-interactive mode (minimal output) can be forced with:
reclaimed ~/Documents --no-interactive
Keyboard Shortcuts
| 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 |
📊 Output
CLI Mode
- 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
Interactive Mode
- 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
🛠️ Development
This project uses UV for building/publishing and Hatch for workflow management.
Setup Development Environment
pip install -r requirements.txt
hatch shell
Common Commands
# Run tests
hatch test
# Build distribution packages
uv build --sdist --wheel
# Create a new release
./release.sh
# Run interactively
python -m reclaimed /path/to/scan
🤝 Contributing
Contributions are welcome!
Please see the Contributing Guide for details.
📜 License
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.