https://github.com/taylorwilsdon/reclaimed
Fast, light and useful - reclaimed is a disk space utilization & cleanup application for macOS, Linux & Windows
https://github.com/taylorwilsdon/reclaimed
cleanup disk-space disk-usage disk-usage-analyzer reclaimed
Last synced: 3 months ago
JSON representation
Fast, light and useful - reclaimed is a disk space utilization & cleanup application for macOS, Linux & Windows
- Host: GitHub
- URL: https://github.com/taylorwilsdon/reclaimed
- Owner: taylorwilsdon
- License: mit
- Created: 2025-02-21T15:09:52.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-07-26T17:27:09.000Z (8 months ago)
- Last Synced: 2025-11-27T16:41:37.833Z (4 months ago)
- Topics: cleanup, disk-space, disk-usage, disk-usage-analyzer, reclaimed
- Language: Python
- Homepage:
- Size: 321 KB
- Stars: 119
- Watchers: 1
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/Textualize/rich) and [Textualize/textual](https://github.com/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)
```bash
uvx reclaimed
```
### Install via pip
```bash
pip install reclaimed
```
### Install via Homebrew (macOS)
```bash
brew install taylorwilsdon/tap/reclaimed
```
### Build from Source
```bash
git clone https://github.com/taylorwilsdon/reclaimed.git
cd reclaimed
pip install -e .
```
---
## 🚀 Usage
### Basic
```bash
reclaimed ~/Documents
```
### Advanced
```bash
# 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:
```bash
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](https://github.com/astral-sh/uv) for building/publishing and [Hatch](https://hatch.pypa.io/) for workflow management.
### Setup Development Environment
```bash
pip install -r requirements.txt
hatch shell
```
### Common Commands
```bash
# 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](CONTRIBUTING.md) for details.
---
## 📜 License
This project is licensed under the **MIT License**.
See the [LICENSE](LICENSE) file for full details.
---
Built with ❤️ for those who love clean disks and clean code.