{"id":50901271,"url":"https://github.com/albertdobmeyer/superclean","last_synced_at":"2026-06-16T03:02:29.477Z","repository":{"id":365118648,"uuid":"1270519899","full_name":"albertdobmeyer/superclean","owner":"albertdobmeyer","description":"An agentic-dev garbage collector for Windows, macOS, and Linux: a tiered RAM, VRAM, and disk cleanup ladder that never kills your active editors, terminals, or AI tools.","archived":false,"fork":false,"pushed_at":"2026-06-16T00:18:05.000Z","size":85,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-16T01:20:34.111Z","etag":null,"topics":["agentic","claude-code","cleanup","cli","developer-tools","disk-cleanup","garbage-collector","linux","macos","powershell","psutil","python","ram","system-maintenance","uv","vram","windows"],"latest_commit_sha":null,"homepage":null,"language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/albertdobmeyer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-15T19:46:16.000Z","updated_at":"2026-06-16T00:18:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/albertdobmeyer/superclean","commit_stats":null,"previous_names":["albertdobmeyer/superclean"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/albertdobmeyer/superclean","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertdobmeyer%2Fsuperclean","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertdobmeyer%2Fsuperclean/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertdobmeyer%2Fsuperclean/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertdobmeyer%2Fsuperclean/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/albertdobmeyer","download_url":"https://codeload.github.com/albertdobmeyer/superclean/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/albertdobmeyer%2Fsuperclean/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34388669,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","claude-code","cleanup","cli","developer-tools","disk-cleanup","garbage-collector","linux","macos","powershell","psutil","python","ram","system-maintenance","uv","vram","windows"],"created_at":"2026-06-16T03:02:28.864Z","updated_at":"2026-06-16T03:02:29.472Z","avatar_url":"https://github.com/albertdobmeyer.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# superclean\n\n**An agentic-dev garbage collector.** One command, a tiered cleanup ladder, that reclaims the RAM, VRAM, and disk left behind by heavy parallel development, and never touches the editors, terminals, or AI tools you have open.\n\n[![PyPI](https://img.shields.io/pypi/v/superclean-cli)](https://pypi.org/project/superclean-cli/)\n![platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue)\n![python](https://img.shields.io/badge/python-3.9%2B-3776AB)\n![license](https://img.shields.io/badge/license-MIT-green)\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo.svg\" alt=\"superclean report then sweep: it finds an orphaned dev server and reclaims 1.45 GB of RAM, leaving 302 protected processes untouched\" width=\"680\"\u003e\n\u003c/p\u003e\n\n## Quick start\n\n```bash\nuvx superclean-cli            # safe read-only report, changes nothing\nuvx superclean-cli sweep      # reclaim RAM/VRAM, kill orphaned dev servers\n```\n\nOr install it once (the command becomes `superclean`):\n\n```bash\npipx install superclean-cli   # or: pip install superclean-cli\n```\n\nWindows, macOS, and Linux. Python 3.9+, one dependency (`psutil`). Start with the\nno-arg report, preview any tier with `--dry-run`, then run it. [Full install and options below.](#install)\n\n## Why this exists\n\nIf you build with Claude Code (or any agentic workflow), your machine looks like this: several IDE windows, a wall of terminals, a fleet of dev servers, repeated Playwright runs, and one or more local models pinned in VRAM. Most of that never cleans up after itself.\n\nDev servers get orphaned when their parent shell dies. Playwright leaves stale browser builds. pip, npm, uv, and pnpm caches balloon. Models stay loaded long after you stopped using them. After a few days the system runs at capacity on garbage.\n\n`superclean` is the collector for that garbage. It tells the difference between work you are actively doing and artifacts you are done with, and only removes the second kind.\n\n## The tiered ladder\n\nCleanup escalates through five additive tiers. Each includes everything lighter. A tier name describes intensity and risk, not a specific action, so the ladder is identical on every OS; each tier does what is available on the current platform and reports what it skipped.\n\n| Command | Tier | What it adds |\n|---------|------|--------------|\n| `superclean` | (none) | Safe read-only **report**. Changes nothing. |\n| `superclean dust` | 1 | Lightest, always-safe: old temp scratch, trivial caches. |\n| `superclean sweep` | 2 | + reclaim live resources: orphan-process kill, RAM/VRAM relief. |\n| `superclean scrub` | 3 | + the standard deep clean: package caches, idle model unload, logs. |\n| `superclean wipe` | 4 | + heavy and deliberate: browser caches, full temp, Playwright builds. |\n| `superclean nuke` | 5 | + destructive: Docker reset, Windows.old. Requires typing `NUKE`. |\n\nRisk rises with the climb: tiers 1-3 are everyday-safe, `wipe` confirms, `nuke` makes you type the word. Plus three utilities: `superclean report`, `superclean ram` (RAM/VRAM relief only, no disk), and `superclean protected` (show what is shielded).\n\n## The safety promise\n\nsuperclean **never** kills your live tools. A generous baseline of editors, terminals, shells, and AI tools is protected by name, together with every one of their child processes, the entire ancestor chain of the running session, and any process whose command line shows it belongs to an AI agent. The tool also protects its own interpreter, so it can never flag itself. When it is unsure about a process, it leaves it alone. You add your own names in `protect.conf`.\n\n## Platform support\n\n| | RAM/VRAM relief | Orphan kill | Cache purge | Deep clean (browser/temp) | Destructive (Docker, Windows.old) |\n|---|---|---|---|---|---|\n| **Windows** | yes | yes | yes | yes | yes |\n| **macOS / Linux** | yes | yes | yes | report-only (v1) | report-only (v1) |\n\nThe everyday tiers do real work everywhere: on macOS and Linux, `dust`, `sweep`, and `scrub` genuinely kill orphaned dev processes, purge package caches, unload idle models, and age out temp files. Only the heaviest, most destructive actions differ by OS: on Windows they are handled by a proven PowerShell deep-clean backend that ships with the package; on macOS and Linux that native destructive deep-cleaning (browser/page cache, docker prune) is report-only in v1 (see Roadmap).\n\n## Install\n\nThe exact same commands work on **Windows, macOS, and Linux** (Python 3.9+).\n\nThe easiest path is [uv](https://docs.astral.sh/uv/) (zero-install, always latest).\nIf you do not already have `uv`:\n\n```bash\n# macOS / Linux\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n```powershell\n# Windows (PowerShell)\npowershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n```\n\nThen, on any OS:\n\n```bash\nuvx superclean-cli              # safe read-only report, changes nothing\nuvx superclean-cli sweep        # reclaim live resources\n```\n\nPrefer a permanent install (gives you the short `superclean` command)?\n\n```bash\npipx install superclean-cli     # macOS: brew install pipx | Debian/Ubuntu: sudo apt install pipx\n# or, simplest:\npip install --user superclean-cli\n```\n\nThe only dependency is `psutil` (prebuilt wheels for Windows, macOS, and Linux,\nso there is nothing to compile). The package is `superclean-cli` on PyPI (the\nname `superclean` was taken); the installed command is `superclean`.\n\n## Recommended workflow\n\n```bash\nsuperclean                  # see what is going on, change nothing\nsuperclean sweep --dry-run  # preview the tier you intend to run\nsuperclean sweep            # do it\n```\n\nStart at the lightest tier that solves your problem: `sweep` for \"too many orphan processes and VRAM is full\", `scrub` for \"disk is filling up\". Reach for `wipe` and `nuke` deliberately.\n\n## Configuration\n\nThree optional files, shared by every platform. superclean looks for them via `SUPERCLEAN_CONF_DIR`, then your per-user config dir, then the bundled examples. Lines starting with `#` are comments.\n\n- **`protect.conf`** - extra process names to never touch (one per line).\n- **`targets.conf`** - extra folders to age out at `scrub` (`path|days|label`). This is where machine-specific cleanup lives so the core stays generic.\n- **`services.conf`** - extra local services to health-check in the report (`label|url`). Ollama is always checked.\n\nEach ships with commented examples, including the author's own \"Albert mode\" setup, to copy from.\n\n## Scripting\n\nEvery command accepts `--json` for a stable machine-readable result (and suppresses human output), so superclean drops cleanly into pre-commit hooks, CI, or a scheduled idle-clean:\n\n```bash\nsuperclean report --json\nsuperclean sweep --dry-run --json\n```\n\nGlobal flags: `--dry-run`, `--yes/-y`, `--i-know` (only with `nuke`), `--quiet/-q`, `--json`, `--no-color`, `--log \u003cpath\u003e`, `--force-unlock`. Exit codes: `0` ok, `1` usage/lock, `3` fatal.\n\n## Logs\n\nEvery run is logged in full under your per-user data directory:\n\n- Windows: `%LOCALAPPDATA%\\superclean\\`\n- macOS: `~/Library/Application Support/superclean/`\n- Linux: `$XDG_STATE_HOME/superclean/` (or `~/.local/state/superclean/`)\n\n## Safety notes\n\nsuperclean deletes files and stops processes. It is built to be conservative, but you are responsible for what you run on your machine.\n\n- Use the no-arg report and `--dry-run` first. Always.\n- `wipe` clears browser caches only when the browser is closed.\n- `nuke` is destructive and irreversible. It requires typing `NUKE` by hand unless you explicitly pass `--yes --i-know`.\n- Provided as-is, no warranty. See [LICENSE](LICENSE).\n\n## Roadmap\n\n- Native destructive deep-clean for macOS and Linux (page cache, `~/Library/Caches`, docker prune).\n- A scheduled \"garbage-collect on idle\" mode.\n- Per-project orphan attribution in the report.\n\n## Development\n\nThe portable core is Python (`src/superclean/`); the Windows deep-clean backend is PowerShell (`windows/`). See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertdobmeyer%2Fsuperclean","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falbertdobmeyer%2Fsuperclean","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falbertdobmeyer%2Fsuperclean/lists"}