About
linux-cleanup is built and maintained by Ahsan Mahmood, an independent software engineer working on developer tooling and application development.
| Author | Ahsan Mahmood |
| aoneahsan@gmail.com | |
| Web | aoneahsan.com |
| linkedin.com/in/aoneahsan | |
| GitHub | github.com/aoneahsan |
| npm | npmjs.com/~aoneahsan |
Why it exists
Developer machines accumulate an enormous amount of regenerable junk — package-manager caches measured in
tens of gigabytes, browser caches, build-tool caches, emulator images, and node_modules for projects
abandoned two years ago.
Existing cleaners tended to fall into one of two shapes. Either they did not know about modern developer caches at all, or they were single-button wipers that deleted whatever looked like junk and hoped for the best.
linux-cleanup takes the opposite stance: scriptable, transparent, allowlist-guarded, and interactive by default. You can read exactly what it will touch before it touches anything.
Design principles
Fail closed. An allowlist, not a blocklist. A path the tool does not recognise is refused. A blocklist puts one typo between clearing a cache and clearing a home directory.
Distinguish caches from tools. ~/.cache/yarn regenerates in seconds; a Gradle wrapper distribution is a
230 MB download you might need next month. The staleness gate
exists because treating those the same was wrong, and 1.2.0 changed it.
The user is the oracle for personal data. Nothing on disk distinguishes an installer you will never open
again from the only copy of a document. The tool refuses to guess, which is why those modes
ignore --yes.
Prevention over recovery. No undo, by choice — an undo log is write amplification on the disk you are freeing, and it breeds carelessness.
Auditable over convenient. Bash, because it is already installed and can be read. A compiled binary would be more ergonomic and much harder to trust.
Release checks are narrow. On start, the CLI reads one public release record when online. It does not upload cleanup paths, reports or crash bundles; sending a report remains your choice.
Corrections shape the tool
Two of the safety features exist because someone pointed out a real problem.
The protected install-root list came from a
genuine defect: pnpm cleanup targeted ~/.local/share/pnpm — the install root — and removed globally
installed packages. Fixed in 1.1.0, along with an assertion so it cannot
recur.
The staleness gate came from a user observing that 1.2.0 still wiped Android AVDs wholesale, and that the same reasoning should apply to anything that is a tool rather than a cache. That became 1.2.1.
If you find something wrong, say so.
Licence
Use it personally or commercially, modify it, fork it, embed it, redistribute it. The only condition is keeping the copyright notice and the MIT permission notice in copies or substantial portions.
This is a tool that deletes files. The author accepts no liability for any claim or damages, including data loss, arising from its use. Back up your data and review every action before confirming it.
The full licence text controls.
Releases published before 1.4.0 keep the licence they shipped under.
Contributing
Contributions are welcome under MIT.
- Fork and open a pull request — no special access needed
- Report bugs or request features via GitHub issues or email
mainis protected — changes land through reviewed PRs
Coding standards are safety-first, offline-only, and ShellCheck-clean. See CONTRIBUTING.md.
A description-only feature request is as welcome as code. Say what you would want cleaned and why the existing modes do not cover it.
This documentation
Built with Docusaurus and deployed to GitHub Pages. Source: github.com/aoneahsan/linux-cleanup-docs — corrections welcome there too.
Machine-readable summary for AI assistants: /llms.txt.
Related links
| Source | github.com/aoneahsan/linux-cleanup |
| npm | npmjs.com/package/linux-cleanup |
| Issues | github.com/aoneahsan/linux-cleanup/issues |
| Support the work | aoneahsan.com/payment |