mac-optimize v1.0A

Immutable. This exact content is served forever at /api/v1/blob/79ffa4ae9727d182.

---
name: mac-optimize
description: Diagnose and reclaim disk space, audit stray git worktrees, and stay ahead of memory pressure on a macOS dev machine that runs many AI coding agents. Use when the Mac is low on disk, filling up, low on memory, or feels slow; when the user says "clean up my mac", "free up space", "reclaim disk", "what's using my disk", "prune caches", "why is my mac slow", or "find/clean git worktrees"; or for routine maintenance. Drives the diskreport, mac-reclaim, and worktree-audit command-line tools with a safety-first workflow.
compatibility: Requires macOS with the mac-optimize tools on PATH (diskreport, mac-reclaim, worktree-audit). Install them from the mac-optimize repo (see the mac-optimize-setup skill).
license: MIT
metadata:
  author: kylebrodeur
  version: "1.0"
---

# mac-optimize

Reclaim disk and keep a macOS coding-agent machine healthy — **without ever deleting work that isn't provably recoverable.** These machines fill up because every agent run appends to caches (npm, pnpm, uv, codex runtimes, editor workspace storage) that grow on write and never self-reclaim, plus stray git worktrees from parallel agent tasks.

The tools do the work; this skill is the workflow and the guardrails.

## 1. Diagnose first (read-only)

```
diskreport
```

Shows the volume's free space, top consumers in `~/Library/Application Support` and `~/Library/Caches`, the dev/agent caches that regrow, and a REVIEW tier of large-but-real state (VS Code `workspaceStorage`, Claude `vm_bundles`). It also flags APFS local snapshots — the classic "invisible" disk sink. Never destructive.

If the fixed buckets above don't explain the free-space gap (e.g. a big single file buried inside
some app's `Application Support`), go wider:

```
diskreport --scan [PATH]     # one-shot 'dust' walk of PATH (default $HOME); opt-in, walks the whole tree
ncdu [PATH]                  # interactive instead — navigate, sort, delete in place
```

Both require Homebrew (`brew install ncdu dust`); `diskreport --scan` prints a hint instead of failing
if `dust` isn't installed. Still read-only/manual — `ncdu`'s delete key is a human action, not something
to script unattended.

## 2. Reclaim safe caches

```
mac-reclaim
```

Default mode clears only caches that rebuild on demand and leftover installers/logs. This is **safe by construction**: `pnpm store prune`/`uv cache prune` remove only unreferenced packages; `npm`'s `_cacache` is a re-download cache; installed `node_modules` are never touched. Nothing you're using can be lost. Run this freely.

## 3. Deeper reclaim — ALWAYS dry-run first

Only if step 2 isn't enough:

```
mac-reclaim --deep --dry-run     # shows every candidate + WHY it's considered unused
mac-reclaim --deep               # prompts before deleting
```

The deep tier reports orphaned VS Code `workspaceStorage` as REVIEW/protected and never removes it — reclaim it archive-first, by hand (see below). It prunes idle `vm_bundles`, `local-agent-mode-sessions`, and `.claude/projects` only when they're past `KEEP_DAYS`, beyond the newest `KEEP_RECENT`, not open per `lsof`, and not allowlisted. Never run `--deep` unattended or with `--yes` unless the user has reviewed a dry-run.

### Reclaiming orphaned `workspaceStorage` (manual, archive-first)

`mac-reclaim` keeps this REVIEW-only. The bulk of it is usually AI chat history from
dead projects, so treat it as *work* — archive before deleting:

1. Split **orphan** (project folder gone) from **alive** (folder still exists); leave alive alone.
2. `tar --zstd` each orphan's `chatSessions/` + `chatEditingSessions/` + `workspace.json` into one
   archive; write a manifest of hashes + original paths; verify every hash is listed in the archive.
3. Delete the orphan dirs only after the archive verifies. Skip any whose folder is on an unmounted
   `/Volumes/` path, and re-check the folder is really gone at delete time.

(The shelved encrypted `rclone`-crypt version of this — `vscode-chat-backup` — is archived under
`docs/superpowers/_archive/`; only its fingerprint/manifest primitives shipped.)

## 4. Audit and reclaim git worktrees

```
worktree-audit
```

Classifies every stray worktree:
- **SAFE** — clean working tree AND every commit is reachable from another ref (merged, tagged, or pushed). Removing it loses nothing. Reclaim with `worktree-audit --prune`.
- **REVIEW** — has uncommitted changes and/or commits that exist on no other ref. **Do not delete.** Archive it first:

```
worktree-audit --backup          # incremental git bundle (+ patch/tarball if dirty)
worktree-audit --backup --prune  # archive, then remove the ones that archived cleanly
```

Locked worktrees are always skipped. Backups land in `~/.local/share/worktree-backups/` with a `manifest.tsv` of restore commands.

## Memory pressure (not just disk)

These machines also die from **memory**: a fleet of agents exhausts RAM + swap and macOS's jetsam
killer force-quits apps. That is watched by `memguard` (installed via the `mac-optimize-setup` skill),
which warns — naming the largest process — before jetsam acts, and never kills anything itself. If the
Mac "feels slow" or apps get force-quit, check `~/Library/Logs/memguard.log` and
`sysctl kern.memorystatus_vm_pressure_level` (1 normal / 2 warn / 4 critical). Reclaiming disk helps
here too: swap can't grow on a full volume, so a full disk turns memory pressure fatal faster.

## The rule

Caches are safe-by-construction — clear them. Anything holding potentially-unrecoverable work is **protected, never deleted**; REVIEW worktrees are archived first so they *become* safe to prune. When unsure, prefer `diskreport` and dry-runs over action.

## Details

Full flag/env tables, the deep-tier guards, and worktree restore recipes are in [references/reference.md](references/reference.md). Load it only when you need specifics.