| name | disk-usage |
| description | Analyse disk fill on a Linux desktop and surface where the space actually went. BTRFS-aware — reports real free space (`btrfs filesystem usage`), unallocated vs allocated, snapshot weight (`btrfs subvolume list` + size estimates), and compression ratio (`compsize`). For ext4/xfs/zfs, falls back to `df -hT` + `du`-based hot-spot detection. Triggers on "where did my disk space go", "check disk usage", "btrfs free space", "df is lying". |
Disk Usage
df lies on BTRFS — it shows allocated space, not free space. This skill gives the truthful picture per filesystem and points at the biggest space sinks.
Steps
- Enumerate filesystems.
findmnt -t btrfs,ext4,xfs,zfs,f2fs -no SOURCE,TARGET,FSTYPE,OPTIONS — one row per real FS. Skip pseudo-FS.
- Per FS, report:
df -hT <mount> — the naive view (note this for BTRFS).- BTRFS:
sudo btrfs filesystem usage <mount> — the truthful view: Device size / allocated / unallocated, Data/Metadata/System breakdown.sudo btrfs filesystem df <mount> — used vs free per profile.sudo btrfs subvolume list -t <mount> — list subvolumes; flag snapshots (typically under @snapshots/, .snapshots/, or named *-snapshot-*).- If
compsize is installed: sudo compsize <mount> for actual compression ratio. Otherwise suggest sudo apt install compsize.
- If usage > 80% of allocated and unallocated is small, suggest
sudo btrfs balance start -dusage=50 <mount> (with a warning that it's I/O heavy).
- ZFS:
zpool list, zfs list -o name,used,avail,refer,mountpoint, zfs list -t snapshot.
- ext4 / xfs:
df -hT is honest. Move on to hot-spot scan.
- Hot-spot scan for the FS the user cares most about (default: the one with least free):
sudo du -h --max-depth=1 -x <mount> 2>/dev/null | sort -hr | head -20 for top-level offenders.- For each offender > a threshold (default 5 GiB), recurse one level:
du -h --max-depth=1 -x <path> | sort -hr | head -10.
- Identify common patterns:
~/.cache, ~/snap, ~/.local/share/Trash, /var/log, /var/cache/apt, /var/lib/docker, /var/lib/flatpak, ~/Downloads.
- Snapshot weight estimate (BTRFS). Use
sudo btrfs filesystem du -s <snapshot-path> per snapshot — note this gives shared/exclusive bytes; the exclusive column is what you'd reclaim by deleting that snapshot.
Output
A short report leading with the truthful free-space number, then a ranked list of "biggest things that aren't sacred":
Filesystem: / (BTRFS)
Device size: 460 GiB
Real free: 38 GiB (df claims 92 GiB — see note)
Note: BTRFS allocated 422 GiB, of which 384 GiB is used. df shows unallocated as "free".
Compression ratio: 1.42x (compsize)
Snapshots: 27 — top weights (exclusive bytes):
/@snapshots/142 8.1 GiB
/@snapshots/138 6.4 GiB
...
Hot-spots in $HOME:
~/.cache 14 GiB
~/.local/share/Trash 9 GiB
~/Downloads 7 GiB
~/.cache/yarn 3 GiB
Suggested next steps:
- Prune old snapshots (snap-it or snapper) — recoverable: ~30 GiB
- Clear ~/.local/share/Trash — recoverable: 9 GiB
- find-duplicates on ~/Downloads
- prune-dev-clutter for stale venvs / node_modules
Notes
- Don't run
btrfs balance automatically. Suggest only.
- Don't delete snapshots — that's
snap-it or snapper's job; this skill only measures.
du on / will hit slow paths (FUSE mounts, network FS) — -x keeps it on one filesystem.
