reclaimed 0.2.8

A powerful disk usage analyzer with iCloud support

reclaimed ♻️

---

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.}