Linux Cleanup — a project by Ahsan Mahmood
A modular Bash and Node.js CLI that safely reclaims regenerable cache and junk disk space for Linux developers.
Disk space on a developer machine goes to things that would rebuild themselves.
Package-manager caches. Browser caches. Gradle, Cypress and Playwright binaries, Android emulator images, and node_modules folders belonging to projects that finished a year ago.
The awkward part is not deleting them.
It is being certain that a given folder is one of those things, rather than the one piece of state on the machine that cannot be regenerated. Linux Cleanup reclaims 10–50+ GB of that junk, and every gigabyte of it is a decision somebody has to be right about.
So the whole tool is built around a single guard.
Every deletion passes through one function, safe_rm, which refuses an allowlist of protected paths. One place to read. One place to audit, and one place a mistake could live. A cleaner that calls rm inside each section has as many chances to get a path wrong as it has sections.
The second guard is time.
Cache cleaners prune by staleness rather than emptying wholesale, so a cache untouched beyond a threshold you set goes and the rest stays. A cache is only junk once nothing has needed it for a while.
The tool runs as a guided 10-step walkthrough, and each step reports the bytes it reclaimed rather than saving a total for the end. That ordering matters more than it sounds: a running total tells you when to stop.
There is also a read-only scan that deletes nothing. There is an all-safe batch mode for the sections that need no judgement, plus a whiptail or dialog interface for anyone who would rather not read flags.
Every run writes a report.
Schema-versioned JSON, with Markdown and a self-contained HTML export on request. The version is on the schema because a report format that changes silently makes last month's report unreadable to this month's script.
It makes no network calls at all.
Nothing about a disk-cleanup tool needs an internet connection, and a program that deletes files and also phones home is asking for a trust it has not earned.
It is a modular Bash engine behind a thin Node.js launcher, published to npm and run with npx linux-cleanup. The launcher is thin on purpose. The part that deletes things is shell, which is the language the rest of the machine is already speaking.
There are installers for a weekly cron entry and a shell alias, for people who would rather this happened without being remembered.
What it cost is the licence.
Linux Cleanup is source-available rather than OSI open source: the licence is No-Derivatives and Non-Commercial. You can read every line before you run it. You cannot ship a modified version of it, and that is worth stating on the page rather than leaving it to be found in a file at the bottom of a repository.
The second cost is the allowlist itself.
A guard that refuses protected paths is also a guard that will occasionally refuse something you genuinely wanted gone, and the honest fix for that is to widen it deliberately rather than to route around it. Every safety rail here is a small amount of friction that somebody eventually resents.
The source is at github.com/aoneahsan/linux-cleanup.
Read the allowlist first. It is the shortest way to learn what the tool will not touch, which is a more useful thing to know than any list of what it will.
What it does, and what that costs to build
- Guided 10-step interactive walkthrough with per-step reclaimed-bytes totals
- Allowlist-based safe_rm guard that refuses protected paths
- Staleness-gated pruning of caches unused beyond N days
- Package-manager, browser, and dev-tool cache cleanup
- Stale node_modules finder across project roots
- Schema-versioned JSON reports with Markdown and HTML export
- Read-only scan, all-safe batch mode, and whiptail/dialog TUI
- Weekly cron and shell-alias installers with zero network calls
Built with
- Bash
- Node.js
- npm
- npx
- jq
- whiptail
- dialog
- cron
- Semantic Versioning
- Diátaxis
Worth knowing
- linux
- cli
- bash
- disk-cleanup
- cache-cleaner
- devtools
- npm
- system-utility
Who built Linux Cleanup?
Ahsan Mahmood, working alone, in Bash with a thin Node.js launcher over the top. The source is at github.com/aoneahsan/linux-cleanup and it is source-available rather than OSI open source: the licence is No-Derivatives and Non-Commercial, which is a limit better read before a fork than after one. Shell is the right language here because the machine being cleaned is already running one, and the launcher exists so that npm can deliver the thing. The person who wrote the delete guard is the person who wrote the report format.
How does it decide a cache is junk?
By age, against a threshold you set. Cache cleaners prune what has gone untouched beyond a number of days rather than emptying a cache wholesale, because a cache is not junk while something is still reading it, and a tool that wipes every cache on principle has simply made your next build slow. The stale node_modules finder works the same way across project roots. That leaves you deciding one number instead of a hundred individual folders, which is the only version of this job anybody does twice.
What stops it deleting a path it should not?
One function. Every deletion passes through safe_rm, which checks its target against an allowlist of protected paths and refuses anything outside it, so there is a single place to read and a single place to be wrong. A cleaner that calls rm inside each section has as many chances to get a path wrong as it has sections. There is also a read-only scan that deletes nothing at all, which is the sensible first run on a machine you have not cleaned before.
Does Linux Cleanup run on macOS or on a phone?
No. It targets Linux, and macOS has a separate tool of mine rather than a flag on this one, because the paths, the cache locations and the package managers differ enough that one script covering both would be wrong in both places. It does not run on a phone in any form. There is no iOS release behind any of my work either, because there is no Apple Developer account here and nothing I build has shipped to the App Store.
What does a run leave behind?
A schema-versioned JSON report, with Markdown and a self-contained HTML export when you ask for them. The schema carries a version because a report format that changes quietly makes last month's report unreadable to this month's script. Nothing leaves the machine: the tool makes no network calls at all, so there is no telemetry, no update check and nothing to opt out of. Per-step reclaimed-bytes totals sit in the report as well, which is how you find out whether the run was worth doing.
https://aoneahsan.com/projects/com.aoneahsan.linuxcleanup