cleanix-cli 1.0.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. cleanix_cli-1.0.1/PKG-INFO +436 -0
  2. cleanix_cli-1.0.1/README.md +401 -0
  3. cleanix_cli-1.0.1/cleanix/__init__.py +4 -0
  4. cleanix_cli-1.0.1/cleanix/__main__.py +6 -0
  5. cleanix_cli-1.0.1/cleanix/cleaners/__init__.py +269 -0
  6. cleanix_cli-1.0.1/cleanix/cleaners/ai_cli.py +193 -0
  7. cleanix_cli-1.0.1/cleanix/cleaners/ai_tools.py +224 -0
  8. cleanix_cli-1.0.1/cleanix/cleaners/app_cruft.py +201 -0
  9. cleanix_cli-1.0.1/cleanix/cleaners/apple_litter.py +41 -0
  10. cleanix_cli-1.0.1/cleanix/cleaners/apps.py +89 -0
  11. cleanix_cli-1.0.1/cleanix/cleaners/apt.py +70 -0
  12. cleanix_cli-1.0.1/cleanix/cleaners/base.py +173 -0
  13. cleanix_cli-1.0.1/cleanix/cleaners/broken_symlinks.py +51 -0
  14. cleanix_cli-1.0.1/cleanix/cleaners/browsers.py +68 -0
  15. cleanix_cli-1.0.1/cleanix/cleaners/bsd.py +108 -0
  16. cleanix_cli-1.0.1/cleanix/cleaners/containers.py +82 -0
  17. cleanix_cli-1.0.1/cleanix/cleaners/coredumps.py +32 -0
  18. cleanix_cli-1.0.1/cleanix/cleaners/desktop_extras.py +42 -0
  19. cleanix_cli-1.0.1/cleanix/cleaners/dev_caches.py +57 -0
  20. cleanix_cli-1.0.1/cleanix/cleaners/distro_pkg.py +127 -0
  21. cleanix_cli-1.0.1/cleanix/cleaners/dnf.py +56 -0
  22. cleanix_cli-1.0.1/cleanix/cleaners/editor_litter.py +115 -0
  23. cleanix_cli-1.0.1/cleanix/cleaners/font_cache.py +29 -0
  24. cleanix_cli-1.0.1/cleanix/cleaners/ide.py +87 -0
  25. cleanix_cli-1.0.1/cleanix/cleaners/kernels.py +115 -0
  26. cleanix_cli-1.0.1/cleanix/cleaners/lang_caches.py +70 -0
  27. cleanix_cli-1.0.1/cleanix/cleaners/linux_extras.py +77 -0
  28. cleanix_cli-1.0.1/cleanix/cleaners/localizations.py +70 -0
  29. cleanix_cli-1.0.1/cleanix/cleaners/logs.py +80 -0
  30. cleanix_cli-1.0.1/cleanix/cleaners/macos.py +166 -0
  31. cleanix_cli-1.0.1/cleanix/cleaners/macos_extra.py +125 -0
  32. cleanix_cli-1.0.1/cleanix/cleaners/memory.py +110 -0
  33. cleanix_cli-1.0.1/cleanix/cleaners/more_pkg.py +168 -0
  34. cleanix_cli-1.0.1/cleanix/cleaners/npm_cache.py +36 -0
  35. cleanix_cli-1.0.1/cleanix/cleaners/packaging_extras.py +140 -0
  36. cleanix_cli-1.0.1/cleanix/cleaners/pacman.py +63 -0
  37. cleanix_cli-1.0.1/cleanix/cleaners/pip_cache.py +27 -0
  38. cleanix_cli-1.0.1/cleanix/cleaners/snapshots.py +126 -0
  39. cleanix_cli-1.0.1/cleanix/cleaners/sys_extras.py +109 -0
  40. cleanix_cli-1.0.1/cleanix/cleaners/temp_files.py +48 -0
  41. cleanix_cli-1.0.1/cleanix/cleaners/thumbnails.py +31 -0
  42. cleanix_cli-1.0.1/cleanix/cleaners/trash.py +47 -0
  43. cleanix_cli-1.0.1/cleanix/cleaners/user_cache.py +69 -0
  44. cleanix_cli-1.0.1/cleanix/cleaners/virtualization.py +76 -0
  45. cleanix_cli-1.0.1/cleanix/cli.py +810 -0
  46. cleanix_cli-1.0.1/cleanix/completion.py +131 -0
  47. cleanix_cli-1.0.1/cleanix/config.py +225 -0
  48. cleanix_cli-1.0.1/cleanix/core/__init__.py +1 -0
  49. cleanix_cli-1.0.1/cleanix/core/context.py +147 -0
  50. cleanix_cli-1.0.1/cleanix/core/engine.py +155 -0
  51. cleanix_cli-1.0.1/cleanix/core/history.py +55 -0
  52. cleanix_cli-1.0.1/cleanix/core/models.py +141 -0
  53. cleanix_cli-1.0.1/cleanix/core/platform.py +117 -0
  54. cleanix_cli-1.0.1/cleanix/core/quarantine.py +147 -0
  55. cleanix_cli-1.0.1/cleanix/core/registry.py +58 -0
  56. cleanix_cli-1.0.1/cleanix/core/report.py +130 -0
  57. cleanix_cli-1.0.1/cleanix/core/safety.py +166 -0
  58. cleanix_cli-1.0.1/cleanix/core/utils.py +244 -0
  59. cleanix_cli-1.0.1/cleanix/reset.py +328 -0
  60. cleanix_cli-1.0.1/cleanix/scheduler/__init__.py +1 -0
  61. cleanix_cli-1.0.1/cleanix/scheduler/systemd.py +160 -0
  62. cleanix_cli-1.0.1/cleanix_cli.egg-info/PKG-INFO +436 -0
  63. cleanix_cli-1.0.1/cleanix_cli.egg-info/SOURCES.txt +68 -0
  64. cleanix_cli-1.0.1/cleanix_cli.egg-info/dependency_links.txt +1 -0
  65. cleanix_cli-1.0.1/cleanix_cli.egg-info/entry_points.txt +2 -0
  66. cleanix_cli-1.0.1/cleanix_cli.egg-info/requires.txt +8 -0
  67. cleanix_cli-1.0.1/cleanix_cli.egg-info/top_level.txt +1 -0
  68. cleanix_cli-1.0.1/pyproject.toml +66 -0
  69. cleanix_cli-1.0.1/setup.cfg +4 -0
  70. cleanix_cli-1.0.1/tests/test_cleanix.py +265 -0
@@ -0,0 +1,436 @@
1
+ Metadata-Version: 2.4
2
+ Name: cleanix-cli
3
+ Version: 1.0.1
4
+ Summary: A safe, thorough scheduled system cleaner for every *nix (Linux, macOS, BSD).
5
+ Author: cleanix-cli contributors
6
+ License: MIT
7
+ Project-URL: Homepage, https://github.com/CloudOpsWorld/cleanix-cli
8
+ Project-URL: Repository, https://github.com/CloudOpsWorld/cleanix-cli
9
+ Project-URL: Issues, https://github.com/CloudOpsWorld/cleanix-cli/issues
10
+ Keywords: cleaner,cleanup,system,maintenance,linux,macos,bsd,cache
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: End Users/Desktop
14
+ Classifier: Intended Audience :: System Administrators
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: POSIX :: Linux
17
+ Classifier: Operating System :: MacOS :: MacOS X
18
+ Classifier: Operating System :: POSIX :: BSD
19
+ Classifier: Programming Language :: Python :: 3
20
+ Classifier: Programming Language :: Python :: 3.10
21
+ Classifier: Programming Language :: Python :: 3.11
22
+ Classifier: Programming Language :: Python :: 3.12
23
+ Classifier: Programming Language :: Python :: 3.13
24
+ Classifier: Topic :: System :: Systems Administration
25
+ Classifier: Topic :: Utilities
26
+ Requires-Python: >=3.10
27
+ Description-Content-Type: text/markdown
28
+ Requires-Dist: rich>=15.0.0
29
+ Requires-Dist: PyYAML>=6.0.3
30
+ Provides-Extra: dev
31
+ Requires-Dist: pytest>=9.1.1; extra == "dev"
32
+ Requires-Dist: ruff>=0.15.21; extra == "dev"
33
+ Requires-Dist: mypy>=2.3.0; extra == "dev"
34
+ Requires-Dist: build>=1.5.1; extra == "dev"
35
+
36
+ # Cleanix CLI
37
+
38
+ [![CI](https://github.com/CloudOpsWorld/cleanix-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/CloudOpsWorld/cleanix-cli/actions/workflows/ci.yml)
39
+ [![PyPI version](https://img.shields.io/pypi/v/cleanix-cli.svg)](https://pypi.org/project/cleanix-cli/)
40
+ [![Python versions](https://img.shields.io/pypi/pyversions/cleanix-cli.svg)](https://pypi.org/project/cleanix-cli/)
41
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
42
+
43
+ A safe, thorough system cleaner for **every *nix flavour** — Linux (all
44
+ major distros), macOS, and the BSDs. It **analyzes** your OS for junk — caches,
45
+ temp files, package-manager leftovers, orphaned packages, broken symlinks,
46
+ package-update config residue, rotated logs, trash, thumbnails, browser/dev
47
+ caches, container cruft — and only **removes** anything after you confirm.
48
+
49
+ It can run on a **schedule** (via a systemd timer) to periodically analyze the
50
+ system and notify you. Scheduled runs *never delete anything*; they only produce
51
+ a report so you can review and clean on your own terms.
52
+
53
+ ## Platform support
54
+
55
+ Cleaners declare which platforms they apply to; `cleanix` auto-detects the OS
56
+ (and Linux distro via `/etc/os-release`) and only runs the relevant ones.
57
+
58
+ | Family | Detected as | Package/system cleaners |
59
+ |----------|------------------------------------|-------------------------|
60
+ | Linux | `linux` + distro id | apt, dnf/yum, pacman, zypper, apk, xbps, portage, flatpak, snap, nix, journald, coredumps, `/var/crash`, `.rpmnew`/`.pacnew`/`.dpkg-old` residue |
61
+ | macOS | `macos` | Homebrew, MacPorts, Xcode (DerivedData/DeviceSupport/simulators), ~/Library caches & logs, Trash |
62
+ | FreeBSD | `freebsd` | pkg cache + autoremove, ports distfiles & work dirs |
63
+ | NetBSD | `netbsd` | pkg, pkgin cache |
64
+ | OpenBSD | `openbsd` | pkg |
65
+ | Cross-OS | all of the above | trash, thumbnails, ~/.cache, temp files, fonts, browser caches, broken symlinks, `.DS_Store`/AppleDouble, dev/language caches (cargo/go/gradle/ccache/composer/…), pip, npm/yarn, Docker, Podman |
66
+
67
+ Run `cleanix list` to see what applies to your machine, or `cleanix list --all`
68
+ to see every platform's cleaners.
69
+
70
+ ## AI / LLM leftovers (triaged, not nuked)
71
+
72
+ Local AI tooling scatters a lot of disposable junk *and* a lot of data you
73
+ deliberately downloaded. Cleanix **triages** — it removes the trash and leaves
74
+ your models and chat history alone:
75
+
76
+ | Tool | Removed (trash) | Kept (your data) |
77
+ |------|-----------------|------------------|
78
+ | **Ollama** | dangling blobs from interrupted pulls, server logs | installed models (referenced blobs/manifests) |
79
+ | **Hugging Face** | `*.incomplete` downloads, `.locks`, `.no_exist` | downloaded model/dataset weights |
80
+ | **PyTorch/Triton/vLLM/CUDA** | Triton, `torch.compile`/inductor, `torch_extensions`, vLLM, `~/.nv/ComputeCache`, FlashInfer JIT caches | — (all pure compile caches) |
81
+ | **LM Studio / Jan** | server logs | models, presets, conversations |
82
+ | **Continue.dev** | rebuildable embeddings index, logs, telemetry | sessions/config |
83
+ | **Claude Code** | throwaway shell snapshots, telemetry cache | projects, history |
84
+ | **Aider** | stray `.aider.tags.cache.*`, `.aider.chat.history.md`, `.aider.input.history` in project trees | — |
85
+
86
+ ### AI coding-agent CLIs (retention-aware)
87
+
88
+ These accumulate rolling backups, per-session file-history/checkpoints, debug
89
+ logs, and transcripts that no built-in command reliably prunes. Cleanix applies
90
+ proper **retention** instead of all-or-nothing deletion:
91
+
92
+ | Tool | Removed | Kept |
93
+ |------|---------|------|
94
+ | **Claude Code** (`~/.claude`) | rolling `.claude.json` backups beyond the newest `keep_backups` (default 2); debug/telemetry/paste/download/changelog caches; stale (>`ai_history_max_age_days`) file-history & transcripts | `~/.claude.json`, `settings.json`, `plugins/`, credentials, **and any currently-running session** |
95
+ | **OpenAI Codex** (`~/.codex`) | session rollouts & TUI logs older than the retention age | recent sessions, config |
96
+ | **Gemini CLI** (`~/.gemini/tmp`) | stale per-project session/log data | config, recent sessions |
97
+ | **OpenCode** (`~/.local/share/opencode`) | logs, snapshots, tool-output | the SQLite DB, auth, storage |
98
+
99
+ Two knobs control retention (see `config/default.yaml`):
100
+
101
+ - `keep_backups: 2` — how many newest rolling backups to keep.
102
+ - `ai_history_max_age_days: 30` — transcripts/history/logs older than this are
103
+ offered (chat history is your data, so it's age-gated and conservative).
104
+
105
+ Per-session scratch (todos, shell snapshots, session env) touched within the
106
+ last day is always left alone, so cleaning never disturbs a live agent session.
107
+
108
+ ## General app bloat
109
+
110
+ - **Electron/Chromium apps** (VS Code, Slack, Discord, Signal, Obsidian, …):
111
+ removes only rebuildable `Cache`/`Code Cache`/`GPUCache`/`Dawn*Cache`/
112
+ `CachedData`/`Crashpad` — **never** `Local Storage`, `IndexedDB`,
113
+ `Service Worker`, or cookies (so you stay logged in). Covers both
114
+ `~/.config/*` and Flatpak (`~/.var/app/*`) apps.
115
+ - **Flatpak app caches** — every app's `~/.var/app/*/cache`.
116
+ - **GPU shader caches** — Mesa (`mesa_shader_cache[_db]`), NVIDIA `GLCache`,
117
+ RADV/AMD Vulkan caches (rebuilt after driver updates).
118
+ - **Steam** — per-game shader caches, interrupted downloads, HTTP cache.
119
+ - **JetBrains IDEs** — caches, logs, and indexes (Linux `~/.cache/JetBrains`,
120
+ macOS `~/Library/Caches/JetBrains`).
121
+
122
+ Cleaners never offer the same path twice: dedicated cleaners own their
123
+ directories and the generic `~/.cache` catch-all defers to them.
124
+
125
+ ## Shell completion
126
+
127
+ ```bash
128
+ cleanix completion bash | sudo tee /etc/bash_completion.d/cleanix
129
+ cleanix completion zsh > ~/.zfunc/_cleanix # a dir on your $fpath
130
+ cleanix completion fish > ~/.config/fish/completions/cleanix.fish
131
+ ```
132
+
133
+ Completes subcommands, options, cleaner ids (for `--only`/`--exclude`) and config
134
+ keys — baked in from the live build.
135
+
136
+ ## Safe memory reclamation (RAM + swap)
137
+
138
+ Opt-in cleaners that free memory **without ever killing or trimming apps**:
139
+
140
+ ```bash
141
+ sudo cleanix clean --only memory --execute # drop clean page/dentry/inode cache
142
+ sudo cleanix clean --only swap --execute # move swap back to RAM (OOM-guarded)
143
+ sudo cleanix clean --only memory_macos --execute # macOS `purge`
144
+ ```
145
+
146
+ - `memory` runs `sync` then `drop_caches` — the kernel only releases *clean*
147
+ cached pages, re-reading from disk later; no process loses data.
148
+ - `swap` runs `swapoff -a && swapon -a` **only when free RAM comfortably exceeds
149
+ swap in use** (20% headroom), so it can never trigger an OOM kill.
150
+ - These are excluded from the default `scan`/`clean` (their effect is transient);
151
+ run them explicitly with `--only`.
152
+
153
+ ## IDE & application coverage
154
+
155
+ - **IDEs** (`ide_caches`): VS Code and forks (VSCodium, Cursor, Windsurf, …)
156
+ logs / `CachedExtensionVSIXs` / stale workspace storage, Sublime, Atom, Emacs
157
+ native-comp cache, Zed logs, Qt Creator, Godot, Unity — plus JetBrains and
158
+ Xcode via their dedicated cleaners.
159
+ - **Apps** (`app_leftovers`, `snap_app_cache`): logs/crash-reports/temp for
160
+ Minecraft, Steam, Heroic, Lutris, Bottles, OBS, Zoom, Skype, Kodi, Nextcloud,
161
+ Dropbox, Ferdium/Rambox, browser crash reports, and every snap's per-app cache.
162
+
163
+ ## Reversible cleaning, history & dashboard
164
+
165
+ - **Quarantine (undo):** `cleanix clean --quarantine` *moves* junk into a
166
+ per-run quarantine instead of deleting it. Undo with `cleanix restore`, reclaim
167
+ the space for good with `cleanix quarantine empty`, review with
168
+ `cleanix quarantine list`. A safety net most cleaners don't offer.
169
+ - **History & stats:** every real clean is logged; `cleanix stats` shows lifetime
170
+ space reclaimed and recent runs.
171
+ - **`cleanix info`:** one-glance dashboard — OS/distro, detected package
172
+ managers, applicable cleaner counts, config path, lifetime cleaned, quarantine
173
+ size.
174
+ - **Parallel scanning** across a thread pool (≈1.4×+ faster), with a live
175
+ progress bar.
176
+ - **`scan --sort size --top N`** to focus on the biggest wins.
177
+ - **User ignore-globs:** `protected_globs` in config adds your own never-delete
178
+ paths on top of the built-in guard.
179
+
180
+ ## Highlights
181
+
182
+ - **Scan first, clean on confirmation.** Nothing is deleted without an explicit
183
+ `--yes` or an interactive confirmation.
184
+ - **Dry-run by default.** `cleanix clean` shows what *would* be removed unless you
185
+ pass `--execute`.
186
+ - **Safe deletes.** A hard-coded protected-path guard refuses to touch critical
187
+ system directories on every platform (`/`, `/etc`, `/usr`, `/System`,
188
+ `/Library`, `$HOME`, `~/Library`, `/usr/ports`, ...).
189
+ - **Orphan & leftover aware.** Finds orphaned packages, residual configs
190
+ (dpkg `rc` state), package-update residue (`.rpmnew`/`.pacnew`/`.dpkg-old`),
191
+ dangling symlinks, and orphaned launcher entries — the cruft "improperly
192
+ designed" packages leave behind.
193
+ - **Accurate sizing.** Uses actual allocated blocks, not apparent size, so
194
+ sparse files don't wildly overstate reclaimable space. Actively-written files
195
+ are left alone (in-use guard).
196
+ - **Modular & platform-gated.** Each junk source is an isolated, auditable module
197
+ that declares the platforms it applies to.
198
+ - **Root-aware.** Cleaners that need root are clearly flagged and skipped (with a
199
+ note) when you run unprivileged.
200
+ - **Scheduling.** Install a systemd timer that scans daily/weekly and reports.
201
+
202
+ ## Install
203
+
204
+ ```bash
205
+ pip install cleanix-cli # from PyPI
206
+ # or from source:
207
+ cd cleanix-cli && pip install -e .
208
+ ```
209
+
210
+ This installs the `cleanix` command. Standalone Linux/macOS binaries are also
211
+ attached to each [GitHub Release](https://github.com/CloudOpsWorld/cleanix-cli/releases).
212
+
213
+ ## Usage
214
+
215
+ ```bash
216
+ # List available cleaners
217
+ cleanix list
218
+
219
+ # Analyze the system (read-only) and print a report
220
+ cleanix scan
221
+
222
+ # Analyze only specific cleaners
223
+ cleanix scan --only trash,thumbnails,apt
224
+
225
+ # Preview what a clean would remove (dry-run, the default)
226
+ cleanix clean
227
+
228
+ # Actually delete, asking for confirmation
229
+ cleanix clean --execute
230
+
231
+ # Delete without prompting (for scripts)
232
+ cleanix clean --execute --yes --only trash,pip_cache
233
+
234
+ # Emit the scan report as JSON (for tooling / notifications)
235
+ cleanix scan --json
236
+
237
+ # Install a systemd timer that scans weekly and notifies you
238
+ cleanix schedule install --frequency weekly
239
+
240
+ # Check / remove the schedule
241
+ cleanix schedule status
242
+ cleanix schedule uninstall
243
+
244
+ # View and change settings (no YAML editing needed)
245
+ cleanix config list
246
+ cleanix config set remove_old_kernels false
247
+ cleanix config set keep_kernels 3
248
+ cleanix config unset keep_kernels # revert to default
249
+
250
+ # See a factory-reset plan for this OS (advisory — runs nothing)
251
+ cleanix factory-reset
252
+ cleanix factory-reset --scope user
253
+ ```
254
+
255
+ ## Configuration via CLI
256
+
257
+ `cleanix config` reads/writes `~/.config/cleanix/config.yaml` with type-checked
258
+ values, so you never have to hand-edit YAML:
259
+
260
+ ```bash
261
+ cleanix config list # every setting, value, source, description
262
+ cleanix config get <key>
263
+ cleanix config set <key> <value> # bool/int/float/list are validated
264
+ cleanix config unset <key> # revert to the built-in default
265
+ cleanix config path
266
+ ```
267
+
268
+ ## Factory-reset advisor
269
+
270
+ `cleanix factory-reset` detects how your OS can be reset and prints a **tiered,
271
+ copy-pasteable plan** — it never executes anything destructive:
272
+
273
+ - **NixOS / Guix** → declarative rollback to a prior generation (✅ reversible)
274
+ - **rpm-ostree** (Silverblue/Kinoite) → `rpm-ostree reset` to the base image (✅)
275
+ - **openSUSE MicroOS** → `snapper rollback` (✅)
276
+ - **macOS** → the built-in "Erase All Content and Settings" (recommended)
277
+ - **Traditional distros** (Fedora/Ubuntu/Arch) → honestly reports there is *no*
278
+ true factory reset; suggests snapshot-restore/reinstall and gives best-effort
279
+ package/config/user reset steps.
280
+
281
+ `--scope user|packages|system|full` controls how much the plan covers.
282
+
283
+ ### Executing a reversible reset
284
+
285
+ On reversible systems only, cleanix can run the rollback for you:
286
+
287
+ ```bash
288
+ sudo cleanix factory-reset --execute
289
+ ```
290
+
291
+ This is heavily gated:
292
+
293
+ - **Only reversible strategies** run — NixOS (`nixos-rebuild switch --rollback`),
294
+ rpm-ostree (`rpm-ostree reset`), MicroOS (`snapper rollback`), Guix
295
+ (`guix system roll-back`). Traditional distros and macOS **refuse to execute**.
296
+ - **Only the reversible rollback command** runs — never the irreversible
297
+ dotfile/`rm -rf` steps (those stay advisory).
298
+ - Requires **root**, an **interactive terminal**, and a **typed confirmation
299
+ phrase** (`reset <hostname>`). Each action prints its **undo** command.
300
+ - Stops on the first failure.
301
+
302
+ Without `--execute`, `factory-reset` only prints the plan.
303
+
304
+ ## System-wide mode (root)
305
+
306
+ Run unprivileged, cleanix scans **your** home. Run as **root/sudo**, it
307
+ automatically sweeps **every real user's home** plus system-wide locations:
308
+
309
+ ```bash
310
+ sudo cleanix scan # all users + system (auto when root)
311
+ sudo cleanix scan --current-user # restrict to the invoking user
312
+ cleanix scan --all-users # force multi-user even unprivileged
313
+ sudo cleanix scan --min-uid 500 # change the "real user" uid threshold
314
+ ```
315
+
316
+ How it works:
317
+
318
+ - Cleaners declare a **scope**: *user* (trash, caches, browsers, AI tools, …)
319
+ or *system* (package managers, `/var/log`, journal, coredumps, …).
320
+ - User-scoped cleaners run **once per target user**, resolving `~`, `~/.cache`,
321
+ `~/.config`, uid, etc. against *that* user — never leaking root's environment.
322
+ - Target users come from `/etc/passwd`: root plus accounts with uid ≥ `min_uid`
323
+ (1000 on Linux/BSD, 500 on macOS) that have a real home directory.
324
+ - Shared/system paths yielded for multiple users are **de-duplicated**, so
325
+ nothing is offered — or deleted — twice.
326
+ - The protected-path guard is extended to cover **every** scanned user's home
327
+ (and their `~/.config`, `~/.local`, `~/Library`, …), so a bug can never wipe
328
+ another user's home.
329
+
330
+ ## Report-only tier (backups & snapshots)
331
+
332
+ Some things are *leftovers* but also *recovery data* — filesystem snapshots,
333
+ mobile-device backups, suspended-VM memory images. Cleanix surfaces these with
334
+ their size and the **correct removal command**, but they are **never** eligible
335
+ for deletion (`clean` skips them; even a forced attempt is refused):
336
+
337
+ ```
338
+ Report-only — review and remove manually (never auto-deleted)
339
+ 7.5 GiB Timeshift snapshot: 2026-01-01 timeshift --delete --snapshot '2026-01-01'
340
+ ```
341
+
342
+ Covered report-only: Timeshift/Snapper snapshots, libvirt saved VM states,
343
+ macOS Time Machine local snapshots, iOS device backups, macOS sleep image.
344
+
345
+ ## Extended coverage
346
+
347
+ Beyond the core cleaners, cleanix also handles:
348
+
349
+ - **Old kernels** — package-manager-driven; always keeps the running kernel and
350
+ the newest `keep_kernels` (default 2). Set `remove_old_kernels: false` to skip.
351
+ - **System caches & spools** — `/var/cache` (PackageKit/man/fontconfig/cups),
352
+ Debian `/var/backups`, ABRT/apport crash spool, staged offline-update payloads.
353
+ - **Language package caches** — Go modcache, rustup/deno/bun/nvm/pnpm, Android
354
+ SDK. Offline repos (Maven/Ivy/sbt/Coursier/NuGet/RubyGems) gated behind
355
+ `include_offline_repos`.
356
+ - **Desktop search indexes** — Baloo, Tracker, Zeitgeist, GVFS metadata.
357
+ - **VM/cloud tooling** — VirtualBox logs, Vagrant boxes, kube/minikube/helm,
358
+ AWS/Azure/gcloud/Terraform/Pulumi caches.
359
+ - **Editor & build litter** — Vim/Neovim swap/undo, `__pycache__`,
360
+ `.pytest_cache`/`.mypy_cache`/`.ruff_cache`/`.tox`, loose core dumps.
361
+ - **macOS extras** — Saved Application State, CocoaPods/Carthage, QuickLook.
362
+ - **Opt-in** (off by default): editor backup files (`*~`/`*.bak`/`*.orig`) via
363
+ `remove_backup_files`, and localepurge-style unused locales/man-pages via
364
+ `purge_unused_locales`.
365
+
366
+ ## Safety model
367
+
368
+ 1. **Two-phase**: `scan` is always read-only. `clean` defaults to dry-run.
369
+ 2. **Protected paths**: deletion of (or inside) critical paths is refused at the
370
+ lowest level — see `cleanix/core/safety.py`.
371
+ 3. **Age thresholds**: temp/log cleaners only consider files older than a
372
+ configurable age, so in-use files are left alone.
373
+ 4. **Scheduled = analyze only**: the timer runs `scan` and writes a report; it
374
+ does not clean.
375
+
376
+ ## Configuration
377
+
378
+ Defaults live in `cleanix/config.py`. Override them with a YAML file at
379
+ `~/.config/cleanix/config.yaml` (see `config/default.yaml` for the shape).
380
+
381
+ ## Project layout
382
+
383
+ ```
384
+ cleanix/
385
+ cli.py # argparse entry point (scan / clean / list / schedule)
386
+ config.py # defaults + YAML overrides
387
+ core/
388
+ models.py # CleanableItem, CleanerReport, dataclasses
389
+ platform.py # OS + distro detection, platform tokens
390
+ context.py # multi-user scanning (target users, current-user binding)
391
+ safety.py # protected-path guard + safe delete
392
+ engine.py # runs cleaners, aggregates reports, executes cleans
393
+ registry.py # discovers, platform-filters & instantiates cleaners
394
+ utils.py # sizes (allocated blocks), walking, age/in-use guards
395
+ report.py # rich tables + JSON rendering
396
+ cleaners/
397
+ base.py # Cleaner ABC (declares .platforms)
398
+ # cross-platform
399
+ trash, thumbnails, user_cache, temp_files, font_cache, browsers,
400
+ broken_symlinks, apple_litter, dev_caches, pip_cache, npm_cache, containers
401
+ # logs & crashes
402
+ logs, coredumps, linux_extras (config residue + /var/crash)
403
+ # linux package managers
404
+ apt, dnf/yum, pacman, distro_pkg (zypper/apk/xbps/portage),
405
+ more_pkg (conda/mamba, guix, eopkg, swupd, opam, sdkman, gem, cpanm),
406
+ packaging_extras (flatpak/snap/nix/appimage)
407
+ # AI / LLM engines & clients
408
+ ai_tools (ollama, huggingface, compile caches, ai clients, aider)
409
+ ai_cli (claude code, codex, gemini cli, opencode — retention-aware)
410
+ # desktop-app bloat
411
+ app_cruft (electron caches, flatpak caches, gpu shaders, steam, jetbrains)
412
+ # extended system leftovers
413
+ sys_extras (/var/cache, /var/backups, crash spool, offline updates)
414
+ kernels (old-kernel purge), localizations (localepurge, opt-in)
415
+ # extended user leftovers
416
+ lang_caches (go/rust/js/.net/jvm), desktop_extras (search indexes)
417
+ virtualization (vbox/vagrant/k8s/cloud), editor_litter (swap/pycache/cores)
418
+ # backups & snapshots (report-only tier)
419
+ snapshots (timeshift/snapper/timemachine/device backups)
420
+ # macOS
421
+ macos (caches, trash, diagnostics, homebrew, macports, xcode)
422
+ macos_extra (saved state, cocoapods, sleep image)
423
+ # BSD
424
+ bsd (freebsd pkg, distfiles/work dirs, pkgin)
425
+ scheduler/
426
+ systemd.py # install/uninstall/status of a user systemd timer
427
+ ```
428
+
429
+ To add a cleaner: subclass `Cleaner`, set `id`/`name`/`platforms`/`requires_root`,
430
+ implement `find_items()` (read-only, yields `CleanableItem`s), and register it in
431
+ `cleaners/__init__.py`. The engine handles dry-run, confirmation, root checks,
432
+ and the safety guard for you.
433
+
434
+ ## License
435
+
436
+ MIT