# reclaimed ♻️
<p align="center">
<img src="https://img.shields.io/github/license/taylorwilsdon/reclaimed?style=flat&logo=github&logoColor=white&label=License&labelColor=555&color=blue" alt="License" />
<a href="https://github.com/taylorwilsdon">
<img src="https://img.shields.io/badge/Privacy-100%25_Client--Side_Processing-blue?style=flat&logo=shield&logoColor=white&labelColor=555" alt="Privacy Shield" />
</a>
<img src="https://img.shields.io/pypi/v/reclaimed?style=flat&logo=pypi&logoColor=white&label=Version&labelColor=005da7&color=blue" alt="PyPI Version" />
<a href="https://pepy.tech/projects/reclaimed"><img src="https://static.pepy.tech/badge/reclaimed" alt="PyPI Downloads"></a>
</p>
<div align="center">
<img width="50%" src="https://github.com/user-attachments/assets/7f02903b-24ca-4415-a929-5a8f89caa99d" />
</div>
---
**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.
---
<p align="center">
<sub>Built with ❤️ for those who love clean disks and clean code.</sub>
</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "reclaimed",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "disk, storage, analyzer, icloud, cli",
"author": null,
"author_email": "Taylor Wilsdon <taylor@taylorwilsdon.com>",
"download_url": "https://files.pythonhosted.org/packages/d3/21/e30516d7e559c5c843da0b2ccb0ae3a83363b1d511749a95210ad4da4d45/reclaimed-0.2.9.tar.gz",
"platform": null,
"description": "# reclaimed \u267b\ufe0f\n\n<p align=\"center\">\n <img src=\"https://img.shields.io/github/license/taylorwilsdon/reclaimed?style=flat&logo=github&logoColor=white&label=License&labelColor=555&color=blue\" alt=\"License\" />\n <a href=\"https://github.com/taylorwilsdon\">\n <img src=\"https://img.shields.io/badge/Privacy-100%25_Client--Side_Processing-blue?style=flat&logo=shield&logoColor=white&labelColor=555\" alt=\"Privacy Shield\" />\n </a>\n <img src=\"https://img.shields.io/pypi/v/reclaimed?style=flat&logo=pypi&logoColor=white&label=Version&labelColor=005da7&color=blue\" alt=\"PyPI Version\" />\n <a href=\"https://pepy.tech/projects/reclaimed\"><img src=\"https://static.pepy.tech/badge/reclaimed\" alt=\"PyPI Downloads\"></a>\n</p>\n\n<div align=\"center\">\n <img width=\"50%\" src=\"https://github.com/user-attachments/assets/7f02903b-24ca-4415-a929-5a8f89caa99d\" />\n</div>\n\n---\n\n**reclaimed** is a cross-platform, ultra-lightweight, and surprisingly powerful command-line tool for analyzing disk usage \u2014 with special handling for iCloud storage on macOS. \nQuickly find your largest files and directories with a beautiful, color-coded interface, and manage them through an interactive terminal UI. \nFully supports **Linux**, **macOS**, and **Windows**.\n\n---\n\n### A quick plug for AI-Enhanced Docs\n\n> **This README was crafted with AI assistance, and here's why that matters**\n> \n> 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.\n>\n> In this case, Sonnet 4 took a pass & a human (me) verified them 6/28/25.\n\n---\n\n## \u2728 Features\n\n- \ud83d\ude80 **Legitimately Performant**: Fast recursive directory scanning with ultra-efficient progress updates.\n - Carefully tuned repaint frequency \u2014 optimized to avoid slowing results by even 5ms.\n - Separate thread for the clock to keep real-time updates buttery smooth.\n- \u2601\ufe0f **iCloud Aware**: Detects and handles iCloud Drive symlink files vs local storage (macOS).\n- \ud83d\udcca **Beautiful UI**: Powered by [Textualize/rich](https://github.com/Textualize/rich) and [Textualize/textual](https://github.com/Textualize/textual).\n - Full keyboard navigation, mouse support, and customizable themes.\n- \ud83d\udda5\ufe0f **Interactive Terminal UI**: Browse, manage, and delete files/directories with ease.\n- \ud83d\uddd1\ufe0f **Safe Deletion**: Remove large files and directories directly from the interface \u2014 with confirmation prompts.\n- \ud83d\udcbe **Export to JSON**: Save scan results for further analysis or batch operations.\n- \u26a1 **Real-Time Feedback**: Live progress indicators and graceful handling of permission issues.\n- \ud83d\udee1\ufe0f **Actual Privacy**: 100% offline. No telemetry, no analytics, no tracking - can't even check for updates.\n\n---\n\nhttps://github.com/user-attachments/assets/1aae04e7-3201-414d-a1e3-6ea5d55bd691\n\n---\n\n## \ud83d\udce6 Installation\n\n### Prerequisites\n- Python 3.8+\n- pip (Python package installer)\n- (Optional but recommended) Use a virtual environment\n\n### uvx (fastest)\n```bash\nuvx reclaimed\n```\n\n### Install via pip\n```bash\npip install reclaimed\n```\n\n### Install via Homebrew (macOS)\n```bash\nbrew install taylorwilsdon/tap/reclaimed\n```\n\n### Build from Source\n```bash\ngit clone https://github.com/taylorwilsdon/reclaimed.git\ncd reclaimed\npip install -e .\n```\n\n---\n\n## \ud83d\ude80 Usage\n\n### Basic\n```bash\nreclaimed ~/Documents\n```\n\n### Advanced\n```bash\n# Show more results\nreclaimed ~/Documents --files 20 --dirs 15\n\n# Skip specific directories during scanning\nreclaimed ~/Documents --skip-dirs node_modules --skip-dirs __pycache__\n\n# Save results to JSON\nreclaimed ~/Documents --output results.json\n```\n\n### Options\n| Option | Description |\n|:------|:------------|\n| `PATH` | Directory to scan (default: current directory) |\n| `-f, --max-files N` | Number of largest files to show (default: 10) |\n| `-d, --max-dirs N` | Number of largest directories to show (default: 10) |\n| `-s, --skip-dirs DIR` | Additional directories to skip (can be specified multiple times) |\n| `-o, --output FILE` | Save results to a JSON file |\n| `-i, --interactive` | Launch the interactive Textual UI |\n\n---\n\n## \ud83c\udf9b\ufe0f Interactive Mode\n\nInteractive mode is on by default. Non-interactive mode (minimal output) can be forced with:\n\n```bash\nreclaimed ~/Documents --no-interactive\n```\n\n### Keyboard Shortcuts\n| Key | Action | | Key | Action |\n|-----|--------|-|-----|--------|\n| `F` | Files view | | `Delete` | Remove item |\n| `D` | Directories view | | `R` | Refresh scan |\n| `S` | Sort items | | `Q` | Quit |\n| `H` | Hide directory | | `U` | Unhide all directories |\n\n---\n\n## \ud83d\udcca Output\n\n### CLI Mode\n- Real-time progress indicator (files scanned, total size)\n- Tables of largest files and directories\n- iCloud vs local storage clearly indicated\n- Summary of any access issues\n\n### Interactive Mode\n- Tabbed interface: switch between Files and Directories\n- Keyboard navigation (arrow keys) and mouse support\n- Sort items by size, name, or path\n- Delete files/directories with confirmation\n- Refresh scan results\n\n---\n\n## \ud83d\udee0\ufe0f Development\n\nThis project uses [UV](https://github.com/astral-sh/uv) for building/publishing and [Hatch](https://hatch.pypa.io/) for workflow management.\n\n### Setup Development Environment\n```bash\npip install -r requirements.txt\nhatch shell\n```\n\n### Common Commands\n```bash\n# Run tests\nhatch test\n\n# Build distribution packages\nuv build --sdist --wheel\n\n# Create a new release\n./release.sh\n\n# Run interactively\npython -m reclaimed /path/to/scan\n```\n\n---\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! \nPlease see the [Contributing Guide](CONTRIBUTING.md) for details.\n\n---\n\n## \ud83d\udcdc License\n\nThis project is licensed under the **MIT License**. \nSee the [LICENSE](LICENSE) file for full details.\n\n---\n\n<p align=\"center\">\n <sub>Built with \u2764\ufe0f for those who love clean disks and clean code.</sub>\n</p>\n",
"bugtrack_url": null,
"license": null,
"summary": "A powerful disk usage analyzer with iCloud support",
"version": "0.2.9",
"project_urls": {
"Homepage": "https://github.com/taylorwilsdon/reclaimed",
"Issues": "https://github.com/taylorwilsdon/reclaimed/issues",
"Repository": "https://github.com/taylorwilsdon/reclaimed.git"
},
"split_keywords": [
"disk",
" storage",
" analyzer",
" icloud",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5e0391058932ae36c541f5af9cdf9d4d19fe6fc819e8d8255d299466085bf3e2",
"md5": "5e145e56d8c60b8a61865f256b0c8983",
"sha256": "a5ca967eecb318949f085fd9bdf3f34c9aceaf98c1e427dbc8f39ba88c3933eb"
},
"downloads": -1,
"filename": "reclaimed-0.2.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5e145e56d8c60b8a61865f256b0c8983",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 46905,
"upload_time": "2025-07-26T17:26:51",
"upload_time_iso_8601": "2025-07-26T17:26:51.422727Z",
"url": "https://files.pythonhosted.org/packages/5e/03/91058932ae36c541f5af9cdf9d4d19fe6fc819e8d8255d299466085bf3e2/reclaimed-0.2.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d321e30516d7e559c5c843da0b2ccb0ae3a83363b1d511749a95210ad4da4d45",
"md5": "ea60cb7e94a7017a3d3dd6fecb7adbc5",
"sha256": "122bb14e5eef1e4bbbece602bf7d2e39a6977f7aa4035bc786adda2eb096e655"
},
"downloads": -1,
"filename": "reclaimed-0.2.9.tar.gz",
"has_sig": false,
"md5_digest": "ea60cb7e94a7017a3d3dd6fecb7adbc5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 42844,
"upload_time": "2025-07-26T17:26:52",
"upload_time_iso_8601": "2025-07-26T17:26:52.414670Z",
"url": "https://files.pythonhosted.org/packages/d3/21/e30516d7e559c5c843da0b2ccb0ae3a83363b1d511749a95210ad4da4d45/reclaimed-0.2.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 17:26:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "taylorwilsdon",
"github_project": "reclaimed",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "click",
"specs": [
[
">=",
"8.0.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"10.0.0"
]
]
},
{
"name": "black",
"specs": [
[
">=",
"22.0.0"
]
]
},
{
"name": "mypy",
"specs": [
[
">=",
"0.950"
]
]
},
{
"name": "hatch",
"specs": [
[
">=",
"1.7.0"
]
]
},
{
"name": "textual",
"specs": [
[
">=",
"2.1.2"
]
]
}
],
"lcname": "reclaimed"
}
JSON
