A macOS shell script that sorts any folder into five safety tiers before you delete it, and previews cache cleanup with a dry run.
Open-source tools · How-to · Mac storage
How to use cache_memory_cleaner: free Mac disk space without losing data
Revised
· v1.0.0 · what changed
Code: github.com/herrrickshaw/cache_memory_cleaner
Watch the walkthrough
Watch on YouTube: youtu.be/W_vkQopqFUg
What it is for
cache_memory_cleaner came out of a real session where a Mac disk was 99% full. Its rule is to remove only what can be rebuilt or is provably backed up.
The key command is classify. Give it a path and it reads git status, whether a running process has it open, whether it sits in a cloud-sync folder, whether the name looks like a personal scan, and how long since anything changed. It prints a tier and the reason. It never deletes anything.
Other commands act on the tier: clean-caches removes browser and package caches (with a dry-run mode), compress-local compresses files in place, and archive-evict uploads to your cloud, checks the bytes, and only then deletes the original.
Who it is for
- Mac users with a nearly full disk who do not want to guess what is safe
- Developers with old virtual environments, repos and VM folders
- Anyone who wants a written reason before deleting something
- Windows or Linux: the script is for macOS
- Automatic cleanup without reading the reasons. classify is a heuristic
- Pointing archive-evict at a folder that another tool syncs (see limits)
What you need
| Requirement | Why | How to get it |
|---|---|---|
| macOS with a shell (zsh or bash) | the script uses macOS tools and paths | already installed |
| git | to clone the repo and for the git checks in classify | xcode-select --install or brew install git |
| rclone (only for archive-evict) | uploads archives to the cloud and verifies them | brew install rclone, then rclone config to set up your remotes |
| afsctool (only for compress-local) | transparent compression. The README warns that ditto --hfsCompression silently does nothing | brew install afsctool |
| Not needed | classify and DRY_RUN clean-caches need no cloud account, no Python and no API keys | nothing to set up |
Get the code and an AI assistant
You do not have to be a programmer. Get the repository, give it to an AI assistant, and ask in plain language. Any of these routes works:
| Tool | What you need | Best for |
|---|---|---|
| GitHub | Free account to fork or star; git to clone, or the green Code button, then Download ZIP, or open in Codespaces | Getting the code and keeping up with updates |
| Claude Code | Claude subscription or API key; run claude inside the cloned folder | Letting the AI read and run the whole repo |
| Gemini CLI | Google account; run gemini inside the cloned folder | The same hands-on workflow with Gemini |
| Claude.ai, Gemini or ChatGPT in the browser | A chat account; upload README.md and the files you care about (or paste the output of git ls-files) | Understanding the project and asking questions without installing anything |
| Other tools (Copilot Chat, Cursor, Codex CLI) | Open the cloned folder in the tool and point it at README.md first | Editing and extending the code |
git clone https://github.com/herrrickshaw/cache_memory_cleaner.git
cd cache_memory_cleaner
claude # or: geminiInstall
- Clone the repo
git clone https://github.com/herrrickshaw/cache_memory_cleaner.git cd cache_memory_cleaner - Make the script executable
chmod +x cache_memory_cleaner.sh - Optional: install the helpers for the commands you plan to use
brew install rclone afsctool
Quick start: commands and what you should see
Ask which tier a pure cache folder belongs to (read-only)
./cache_memory_cleaner.sh classify path/to/myproj/__pycache__RECOMMENDATION: Tier 4, delete immediately, no backup needed, because the name matches a known cache pattern that regenerates.
Classify a Python virtual environment
./cache_memory_cleaner.sh classify path/to/venvTier 1, permanent local, compress in place. It can be rebuilt from requirements.txt, but until then something needs it as real files.
Classify a folder untouched for years
./cache_memory_cleaner.sh classify path/to/oldvmIn the demo, a folder dormant for 1,386 days and untracked came back as Tier 3: archive to the cloud, then evict. A git repo with a branch that has no upstream also got Tier 3 (git bundle). A path matching a personal scanned-document pattern got Tier 0, never touch.
Preview cache cleanup without deleting anything
DRY_RUN=1 ./cache_memory_cleaner.sh clean-cachesLines starting [dry-run] rm -rf, covering browser caches, Chrome's on-device model caches, Chrome Service Worker and GPUCache folders, and pip caches. The demo ended with 'Free space: 21GB -> 21GB', since nothing was removed.
Ways to use it
| Method | How it works |
|---|---|
| Command line | ./cache_memory_cleaner.sh <command>. Commands in the README: report, clean-caches, clean-packages, find-dormant, git-gc, trim-vms, archive-evict, list-archives, compress-local, classify and all. |
| Dry run | Put DRY_RUN=1 in front of any command to print what it would do. |
| Via an AI assistant | Ask the assistant to run classify on a folder and explain the reason in plain language before you act. |
Sample prompts for your AI assistant
Copy, paste and edit the parts in [brackets].
- Read README.md and cache_memory_cleaner.sh and explain the five tiers in plain English.
- Run classify on [path] and tell me what each check means and what the recommendation is.
- I want to free about [20] GB. Run report, then suggest which folders to classify first. Do not delete anything.
- Run DRY_RUN=1 clean-caches and explain each line it would remove and whether apps rebuild it.
- Explain the risk if CLEANER_REMOTES points at a folder that another rclone sync job also writes to.
- Help me set up rclone and a safe archive-evict destination, and confirm the destination is not synced by anything else.
Limits and honest caveats
- classify is a heuristic. Read its reason, and the tier policy document in the repo-data-dedup repo, before acting on it.
- Never point CLEANER_REMOTES at a path that another job mirrors with rclone sync. A sync job deletes remote files it does not find locally; in the author's case this wiped four verified archives.
- compress-local needs afsctool. ditto --hfsCompression silently does nothing.
- archive-evict needs rclone remotes already configured. It deletes originals, so it was not run in the demo.
- The demo ran only classify (on example folders) and a dry run of clean-caches. It did not run report, find-dormant, trim-vms, archive-evict or compress-local.
- The demo's classify paths were example folders, not a real system, and no files were deleted.
Sources: README.md and cache_memory_cleaner.sh in github.com/herrrickshaw/cache_memory_cleaner (MIT licence); demo run on 18 October 2026.
- v1.0.0 — 18 October 2026 — first published.
About this article: Researched, written and edited by Umashankar Triplicane Dwarakanathan, with AI research assistance; every figure is meant to trace to the primary source cited. See the Editorial Policy for how sourcing, AI use and corrections work.
