free-my-arch

Disk cleanup for Arch Linux, packaged as a Claude Code skill.

It scans the usual suspects (package caches, AUR build leftovers, dev caches, Docker junk, oversized files sitting in your home) and walks you through cleaning them up. Caches are confirmed as groups, personal files are picked one by one. Nothing is ever deleted without your explicit approval.

Why

My root partition hit 88% and most of that space turned out to be garbage: 14 GB of yay build cache, 18 GB of npm cache, node_modules for projects I had not touched in months, a pile of dangling Docker images. Cleaning that by hand means remembering a dozen different commands and their gotchas. This skill remembers them for you, shows you the numbers first, and asks before running any of them.

How it works

The skill follows four strict phases:

1. Scan. A bundled shell script measures every category. It is strictly read-only and needs no root.
2. Report. You get a summary table with the reclaimable space per group, plus a numbered list of large personal files.
3. Confirm. Cache groups are approved with a single multi-select prompt. Large files are selected individually, so you never bulk-delete personal data by accident.
4. Clean. Only what you approved gets removed. A final report shows disk usage before and after.

What it scans

A few things get extra care:

• Docker volumes are never part of a group clean. If unused volumes exist they get their own explicit confirmation, because volumes hold real data.
• Orphan packages are listed in full before removal. If the list contains something that looks load-bearing (a running Docker daemon, compilers, your AUR helper), the skill points it out instead of silently removing it.
• Files living under hidden directories (Thunderbird mail stores, VM images, model weights) are flagged as APP-DATA and kept out of the normal selection. Deleting those can break the owning application, so they are only surfaced with a warning.

Install

Clone into your Claude Code skills directory:

git clone https://github.com/debba/free-my-arch ~/.claude/skills/free-my-arch

That's it. Claude Code picks it up automatically.

Usage

/free-my-arch        # default threshold for large files: 500M
/free-my-arch 1G     # only report personal files above 1 GB

You can also just ask in plain language ("my disk is full, help me clean it up") and Claude will reach for the skill on its own.

Requirements

• Arch Linux or a derivative
• Claude Code
• Optional: pacman-contrib for precise pacman cache estimates. docker and flatpak are detected and skipped when absent.

Safety rules baked into the skill

• The scan phase never deletes anything, no exceptions
• Configs, dotfiles, browser profiles, /etc and the pacman database are off limits
• rm is never run on a glob or an unchecked variable
• sudo is only used for the system group, and only after you confirmed that group
• Answering "none" at any prompt simply skips that category

Repository layout

SKILL.md                    the skill definition Claude follows
scripts/scan.sh             the read-only scanner
references/categories.md    cleanup commands per category, with safety notes

License

MIT