Metadata-Version: 2.5
Name: bloatr
Version: 0.2.0
Summary: Kill your Mac's bloat. Select. Delete. Done.
Project-URL: Homepage, https://github.com/suhasdinesh/bloatr
Project-URL: Repository, https://github.com/suhasdinesh/bloatr
Project-URL: Bug Tracker, https://github.com/suhasdinesh/bloatr/issues
License: MIT
Keywords: cleanup,developer,disk,macos,storage
Requires-Python: >=3.11
Requires-Dist: textual>=0.60
Description-Content-Type: text/markdown

<div align="center">

# bloatr

**Kill your Mac's bloat. Select. Delete. Done.**

[![PyPI](https://img.shields.io/pypi/v/bloatr?color=ff6b6b&label=pypi)](https://pypi.org/project/bloatr/)
[![Python](https://img.shields.io/pypi/pyversions/bloatr?color=4ecdc4)](https://pypi.org/project/bloatr/)
[![License: MIT](https://img.shields.io/badge/license-MIT-a8e6cf)](LICENSE)
[![Platform](https://img.shields.io/badge/platform-macOS-c3b1e1)](https://github.com/suhasdinesh/bloatr)

A macOS CLI for developers who've run out of disk space one too many times.  
Finds Docker leftovers, dev caches, app caches and build artifacts, lets you explore and delete them safely — with a live progress bar.

<!-- Replace with demo.gif once recorded -->
![bloatr screenshot](screenshot.svg)

</div>

---

## Install

```bash
pipx install bloatr
```

<details>
<summary>Or with pip</summary>

```bash
pip install bloatr
```

</details>

---

## Usage

```bash
# Launch interactive TUI — scans known bloat locations + Docker
bloatr

# Scan any directory, like `du` but interactive
bloatr ~/
bloatr ~/Library/Caches
bloatr ~/Documents

# Safe preview — see what would be deleted without touching anything
bloatr --dry-run

# Leave Docker alone
bloatr --no-docker

# Only show items larger than a threshold
bloatr --min-size 1G

# JSON output — pipe-friendly
bloatr --json
bloatr --json | jq '.[].size_human'
```

---

## How it works

1. **Scan** — measures ~60 known bloat locations plus Docker in parallel (a few seconds)
2. **Read** — every row says what it is, whether it's `safe` or `caution`, and warns you if the owning app is running
3. **Select** — `Space` on items, or `A` to grab everything marked `safe` in one go
4. **Delete** — `D`, confirm, watch the progress bar. bloatr reports the real change in free disk space when it's done

Where a tool has its own cleanup command, bloatr uses it instead of deleting files — `docker … prune`, `uv cache clean`, `npm cache clean`, `go clean -modcache` — but only after checking the tool really stores its cache at the path you selected.

---

## What it finds

| Category | Examples |
|---|---|
| **Docker** | Build cache, unused images, unused volumes, stopped containers — via `docker system df`, cleaned with `docker … prune` (never by touching `Docker.raw`) |
| **Xcode** | DerivedData, Archives, iOS/watchOS DeviceSupport, simulator caches, devices and runtimes |
| **Dev caches** | uv, pip, Poetry, pre-commit, npm, pnpm, Yarn, Bun, Gradle, Maven, CocoaPods, Cargo, Go, Flutter/Dart, Expo, Playwright, Puppeteer, JetBrains, Android SDK & emulators, Homebrew |
| **AI models** | Hugging Face, Ollama, Claude desktop's VM image, Chrome's on-device Gemini Nano |
| **App caches** | Claude, Cursor, VS Code, Slack, Chrome (every profile), Discord, Spotify, `~/Library/Caches` |
| **Messages** | WhatsApp media, Mail attachments |
| **System** | Trash, `~/Library/Logs` |

Empty and missing locations are hidden. `caution` means re-downloading or your own data (WhatsApp media, Docker volumes, AI models) — `A` never selects those.

> **Tip:** Don't see a location you care about? Run `bloatr ~/` to scan your entire home directory.

---

## Keyboard shortcuts

| Key | Action |
|---|---|
| `j` / `↓` | Move down |
| `k` / `↑` | Move up |
| `space` | Toggle select |
| `a` | Select / deselect everything marked `safe` |
| `enter` | Drill into folder |
| `esc` / `backspace` | Go back |
| `d` | Delete selected items |
| `r` | Rescan from scratch |
| `q` | Quit |

---

## Safety

bloatr will **never** delete:

- Anything outside your home directory (`~`)
- Top-level protected directories — `~/Library`, `~/Documents`, `~/Desktop`, `~/Pictures`, `~/Downloads`, and more
- Anything *inside* those personal directories (Documents, Desktop, Downloads, etc.)
- The home directory itself
- Docker's disk image directly — Docker space is only ever freed through `docker … prune`

Cleanup commands are limited to an allow-list (`docker`, `uv`, `npm`, `go`) and come only from bloatr's built-in catalog.

Every deletion requires an **explicit confirmation prompt**. Use `--dry-run` to simulate a cleanup run without touching the filesystem.

---

## Credits

Idea and direction by a developer who lost 100 GB to Xcode caches one afternoon.  
Code written entirely by [Claude Code](https://claude.ai/code).

---

## License

MIT
