reclaim-space

Files (6)

• SKILL.md
• eval_queries.json · evals/
• evals.json · evals/
• smart-playlist-recipe.md · references/
• audit-library.sh · scripts/
• build-offload-playlist.sh · scripts/

SKILL.md (first lines)

## 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
bash scripts/audit-library.sh --keep-folder "Crates"
```

Present the JSON: the cloud-status histogram, the `cloud_safe` total, and the
keep-folder playlists. Then:

- If `sync_library_likely_on` is `false` (or `cloud_safe` is 0), STOP: do not
  build a playlist. Sync Library is off or nothing is in iCloud, so removing
  downloads would lose that music for good. Tell the user to turn on Sync
  Library (and let it finish) or archive to the NAS first.
- If `cloud_status.ineligible` is high, warn that those are local-only; they are
  never added to the playlist (it takes only cloud-backed tracks) but are worth
  archiving to the NAS.
- Otherwise go on to Step 2.

### Step 2: Build the offload playlist

Building the playlist is safe: it only collects tracks and removes nothing. If
the user has named their protections (the keep folder, a Grouping prefix),
build it straight away with those; if not, ask for them first. Then build it:

```bash
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:
1. Open the playlist in Apple Music and **sanity-check the count** matches
   `in_playlist`.
2. **Test on a small batch first**: select ~50 tracks → right-click → **Remove
   Download** → confirm they show the cloud icon and still stream.
3. 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](references/smart-playlist-recipe.md).

From eyelock/assistants, MIT.

More from eyelock/assistants