| name | reclaim-space |
| description | Reclaim local disk by offloading cloud-backed Apple Music downloads. Audit iCloud status, build an offload playlist that protects your DJ crates and lossless files, then Remove Download. Use when the Mac is low on disk. |
| allowed-tools | Bash Read |
| metadata | {"author":"eyelock","version":"0.1.0"} |
Setup
This skill talks to the Apple Music app via AppleScript, so it requires macOS
with Music scriptable (the terminal must have Automation permission for Music —
macOS prompts once on first run).
There are no path environment variables to resolve; everything operates on the
Music library, not the filesystem.
Scripts are in scripts/ relative to this skill directory.
Scripts
audit-library.sh [--keep-folder <name>] — Read-only. Reports the iCloud
status histogram (how many tracks are cloud-backed vs Ineligible) and the
playlists inside the keep folder. Run --help for details.build-offload-playlist.sh [options] — Creates a playlist of tracks that
are safe to offload. Non-destructive (never removes downloads). Run --help.
Concept
Apple Music can re-download any track whose iCloud status is Matched,
Uploaded, Purchased, or Subscription — so removing its local
download is reversible and frees disk. Tracks that are Ineligible (often
WAV/large lossless) have no cloud copy; removing those is permanent data
loss, so they must be excluded (those belong on the NAS — see archive-media).
Apple's Smart Playlist editor has no "is downloaded" condition, and its
automation cannot author Smart Playlist rules. The workaround: build a playlist
of everything safe to offload, then run Remove Download on the whole list
(a no-op on anything not currently downloaded, so it is always safe to run).
Workflow
Step 1: Audit — confirm Sync Library is on and see what's offloadable
bash scripts/audit-library.sh --keep-folder "Crates"
Present the JSON: the cloud-status histogram, the cloud_safe total, and the
keep-folder playlists. Confirm with the user before going further:
- If
sync_library_likely_on is false (or cloud_safe is 0), STOP — Sync
Library is off, nothing is in the cloud, and offloading would lose data.
- If
cloud_status.ineligible is high, warn that those are local-only; they are
excluded by the Kind filter below but worth archiving to the NAS.
Step 2: Build the offload playlist
Ask the user for their protections, then build it:
bash scripts/build-offload-playlist.sh \
--playlist "Offload — Cloud Safe" \
--keep-folder "Crates" \
--exclude-grouping "DJ" \
--exclude-kind "WAV" \
--replace
--keep-folder protects every playlist inside that folder (e.g. recency
crates and genre crates that feed Rekordbox).--exclude-grouping protects tracks tagged for active use (e.g. Grouping
starting DJ).--exclude-kind protects local-only formats (default WAV).
This can take a few minutes on a large library — it adds tracks one at a time.
Report in_playlist and the excluded breakdown.
Step 3: Free the space — MANDATORY user step, never automate
Tell the user to:
- Open the playlist in Apple Music and sanity-check the count matches
in_playlist.
- Test on a small batch first: select ~50 tracks → right-click → Remove
Download → confirm they show the cloud icon and still stream.
- Once trusted: ⌘A → right-click → Remove Download.
DO NOT run Remove Download for the user via automation. Surface the count
and the magnitude (it can be most of the library) and let them pull the trigger.
Auto-updating alternative
The built playlist is a snapshot — re-run Step 2 (with --replace) to refresh
it. For a hands-off, always-current version, build the Smart Playlist by hand
once using references/smart-playlist-recipe.md.
