An agent skill that reclaims disk space on Linux by clearing caches and old installation files — with full visibility and per-task control.
FreeSpace is a small set of bash scripts that an LLM agent (or you, directly) can use to free disk space safely. Every task shows you what it will delete and how big it is before doing anything. Nothing is removed without your confirmation.
The bundled skill at skill/freespace/ is a plain markdown spec (SKILL.md) plus the scripts — agent-agnostic, no framework lock-in. It works with any LLM agent that can read a markdown instruction file and shell out to bash.
| Script | Distros |
|---|---|
skill/freespace/ubuntu.sh |
Ubuntu, Debian, Pop!_OS, Mint, Elementary (apt) |
skill/freespace/fedora.sh |
Fedora, RHEL, CentOS, Rocky, AlmaLinux (dnf / yum) |
The skill auto-detects the distro via /etc/os-release.
Per-task, both scripts cover:
- pip cache (
~/.cache/pip) — often tens of GB on ML systems - npm cache (
~/.npm) - Trash (
~/.local/share/Trash) - Docker build cache — keeps all images and volumes
- Package manager cache + unused packages (
apt clean/dnf clean all+autoremove) - systemd journal logs — vacuum to last 7 days
- Old rotated logs in
/var/log/*.gz,*.1,*.old - Old CUDA installer repos in
/var/cuda-repo-* - Old CUDA versions in
/usr/local/cuda-*(a keep-list at the top of the script protects current versions) - Crash reports (
/var/crash, plus ABRT on Fedora/RHEL)
Run bash <script> --list for the authoritative list on your host.
The recommended way to use FreeSpace is to install it as a skill on your LLM agent and let the agent drive it. The agent gets distro detection, dry-run-first workflow, per-task confirmation, and before/after disk-usage reporting for free.
skill/freespace/SKILL.md is the agent-facing instruction file. It tells the agent how to:
- Detect the host distro and pick the correct script.
- Always run
--dry-runfirst and surface each task's target + size to the user. - Wait for the user to choose which tasks to actually run.
- Hand sudo-needing commands back to the user instead of escalating silently.
- Report before/after
df -h /so the freed space is visible.
Install paths vary per agent runtime. A few examples:
# Generic: drop the skill folder anywhere your agent loads skills/instructions from
cp -r skill/freespace /path/to/agent/skills/
# Claude Code (one common option)
mkdir -p ~/.claude/skills && cp -r skill/freespace ~/.claude/skills/Then ask the agent things like "free up some disk", "I'm running out of space on /", or "what's filling my disk?" — the SKILL.md will guide it through the dry-run-first workflow.
If your runtime doesn't have a skill loader, you can also paste the contents of SKILL.md into the agent's system prompt or instructions field — it's plain markdown by design.
You can also run the scripts directly without an agent.
# preview everything, change nothing
bash skill/freespace/ubuntu.sh --dry-run
# interactive: confirm each task before running
bash skill/freespace/ubuntu.sh
# run only a single task
sudo bash skill/freespace/ubuntu.sh --task journal
# all tasks, no prompts (use with care)
sudo bash skill/freespace/ubuntu.sh --yes
# list tasks
bash skill/freespace/ubuntu.sh --listSame flags work for fedora.sh.
User-level tasks (pip, npm, trash, docker_builder) run as your user. System tasks (apt/dnf, journal, /var/*, /usr/local/*) need sudo.
Both scripts have a CUDA_KEEP=(...) array near the top. Versions listed there are never removed from /usr/local. Edit it before running --task cuda_old if your active CUDA version isn't already in the list.
- Dry-run is opt-out, not opt-in.
- Each task has a
describe_*function that runs first, before anyrun_*. - Scripts use
set -uo pipefail; failures in one task don't cascade. - The CUDA keep-list prevents accidental removal of the version you're using.
- No script ever touches
/homedata, dotfile configs, or anything outside the explicit task targets.
MIT.