mac-optimize-setup v1.0A

Immutable. This exact content is served forever at /api/v1/blob/43fc4fce0bdd7260.

---
name: mac-optimize-setup
description: Install and configure the mac-optimize disk and shell hygiene toolset on a macOS machine, including the launchd automation (a low-disk watcher plus a weekly reclaim) and optionally moving a 1Password service-account token out of a cleartext dotfile into the login Keychain. Use when setting up a new Mac, when the user says "install mac-optimize", "set up disk automation", or "set up the disk cleanup tools", or when uninstalling them.
compatibility: Requires macOS, git, and a checkout of the mac-optimize repo. Homebrew, pnpm, uv, and nvm are optional (their caches are only pruned if present).
license: MIT
metadata:
  author: kylebrodeur
  version: "1.0"
---

# mac-optimize-setup

Install the mac-optimize tooling (`diskreport`, `mac-reclaim`, `worktree-audit`, `diskguard`) and its launchd automation onto a Mac.

## Install

From a checkout of the repo:

```
git pull            # if already cloned
make install
```

`install.sh` is idempotent. It copies `bin/*` to `~/.local/bin` (make sure that's on `PATH`), installs the two launchd plists to `~/Library/LaunchAgents`, and (re)loads them.

## Verify

```
launchctl list | grep mac-optimize    # expect com.mac-optimize.diskguard and .mac-reclaim
diskreport                            # confirm the tools resolve on PATH
```

`diskguard` runs at login and every 3 hours; if free space drops below 20 GB it runs a safe reclaim and posts a notification (urgent notice, no auto-delete, below 10 GB). `mac-reclaim` runs a safe reclaim weekly.

**One-time macOS permission:** the first low-disk notification may need Notification Center permission for `osascript`/Script Editor (System Settings → Notifications). The reclaim still runs regardless; only the banner is gated.

## Optional: secure a 1Password service-account token

If a `OP_SERVICE_ACCOUNT_TOKEN` is exported in cleartext in a shell dotfile, move it into the login Keychain (never print the value):

```
# store (from a shell where the token is currently set)
security add-generic-password -a "$USER" -s op-service-account-token \
  -w "$OP_SERVICE_ACCOUNT_TOKEN" -T /usr/bin/security -U

# verify it authenticates, then replace the dotfile line with:
export OP_SERVICE_ACCOUNT_TOKEN="$(security find-generic-password -a "$USER" -s op-service-account-token -w 2>/dev/null)"
```

The `-T /usr/bin/security` grant lets the shell read it at startup without a prompt. Confirm with `op whoami` before removing the cleartext.

## Uninstall

```
make uninstall      # bootout both launchd agents, remove plists + deployed scripts
```

The repo (source of truth) is left intact.

## Using the skills with any agent

The skills in this repo's `skills/` directory follow the open [Agent Skills](https://agentskills.io) format (`SKILL.md` per folder). Point any skills-compatible agent at them, or for Claude Code symlink each folder into `~/.claude/skills/`. Validate with `skills-ref validate ./skills/<name>`.