Ops Mac

OPS ► MAC — macOS Diagnose & Fix

Load ops-rules before acting. Public repo (no personal data). Outbound: one draft → one approval → one send. If AskUserQuestion / Workflow are missing, follow Rule 10 in ops-rules (Hermes: numbered options / two-turn Telegram card; delegate_task).

One command for native macOS health: it bundles the macos-toolkit CLI suite, auto-installs it on first use, runs a read-only baseline, and remediates the common offenders behind explicit confirmations.

All work routes through ${CLAUDE_PLUGIN_ROOT}/bin/ops-mac, the single source of truth for install + probes + the aggregate audit. The bundled CLIs:

Platform guard

This skill is macOS only. The dispatcher exits with code 3 on non-Darwin. For Linux/WSL/Windows system optimization use /ops:speedup (cross-platform). The two are complementary — /ops:mac is the deep macOS-native surface; /ops:speedup is the portable cleaner.

Two hard-won quirks (baked into the dispatcher)

1. machealth check/diagnose can hang forever on a stuck Time Machine / iCloud probe (its checks run in parallel with no per-probe skip flag). Every machealth call is wrapped in a hard timeout (default 25s, override OPS_MAC_MACHEALTH_TIMEOUT). If it trips, the other probes are still reliable — never block on it.
2. The toolkit's pretty TUI tables render EMPTY when stdout isn't a TTY. The dispatcher forces --json for headless/agent consumers (macbroom, pstop, macdog, lanchr). When you need machine data, always pass --json.

Runtime Context

Before anything, ensure the suite is installed (idempotent — no-op if already present):

Copy code
${CLAUDE_PLUGIN_ROOT}/bin/ops-mac ensure

Mode routing

Dispatch on $ARGUMENTS:

• empty / audit → Baseline flow (read-only, below)
• health / net / disk / procs / security / launchd / power / update → run that single probe and print verbatim:

  bashCopy code
  ${CLAUDE_PLUGIN_ROOT}/bin/ops-mac <subcommand>
  

• fix → Remediation flow (below, Rule 5 confirmations)
• ensure / install → run ops-mac ensure and report what was added

Baseline flow (/ops:mac or /ops:mac audit)

Run the aggregate audit — it composes the reliable probes in one call:

Copy code
${CLAUDE_PLUGIN_ROOT}/bin/ops-mac audit

Then summarize for the user with a verdict per area:

Copy code
OPS ► MAC AUDIT — [version] ([arch])

🔴/🟡/🟢 Security    grade [X]/100 — [firewall/SIP/FileVault/Gatekeeper/remote-login]
🔴/🟡/🟢 Launchd     [N] genuinely-broken user daemons (Apple -9/SIGKILL noise filtered out)
🟢 Processes  top hog: [name] [N]% CPU
🟢 Network    [iface] [ip] — [ok/degraded]
🟢 Disk       ~[N] GB safe reclaimable (biggest: [cache] [N] GB)
⚠ Health     [machealth result, or "probe timed out — TM/iCloud stuck"]

Next: /ops:mac fix to remediate, or pick one area.

Launchd noise filter — lanchr doctor flags ~50+ "critical" entries; most are normal:

• Apple on-demand agents exit -9 (SIGKILL) when idle — expected, not broken.
• Stale Apple plist paths (cvmsCompAgent, BluetoothUIService, battery helper) — cosmetic.
• The actionable ones are user/3rd-party daemons with exit status: 1 or a missing binary you own. Surface only those.

Remediation flow (/ops:mac fix)

Run the audit first to know what's wrong, then offer fixes. Per plugin Rule 5, every mutating action needs its own confirmation — never batch-execute. Present via AskUserQuestion, max 4 options each.

Common offenders and their guarded fixes:

1. Firewall — opt-in only, never offered

The application firewall is out of scope for /ops:mac fix. Report its state in the audit and stop there. Do not offer to enable it, do not add it to a fix menu, and do not list it as a recommendation — a firewall that comes on unasked breaks local listeners (dev servers, MCP proxies, VNC, tunnels) that the user did not connect the change to.

Touch it only when the user asks for the firewall by name in that turn ("turn the firewall on", "enable stealth mode"). Then confirm the single action and run:

bashCopy code
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on
# stealth (optional): sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setstealthmode on

"Run /ops:mac fix" is not that request.

2. Stale / crashing launchd user daemons

For each actionable entry from lanchr doctor (missing binary, or repeated exit 1), confirm individually:

Copy code
com.example.foo — binary missing at [path]. This launchd job is dead.
  [Show the plist first]  [Remove it]  [Disable (keep file)]  [Skip]

Use lanchr to remediate where possible; otherwise launchctl bootout/disable after showing the plist. Never touch a daemon the user relies on (CLIProxyAPI/haproxy, gbrain push, ops-daemon, cloudflared tunnels, watchdogs) without spelling out exactly what it is — cross-check before recommending removal.

3. Reclaimable disk

Copy code
macbroom found ~[N] GB of safe cache. Categories: [list].
  [Clean safe caches]  [Pick categories]  [Review largest first]  [Skip]

On confirm (safe categories only):

bashCopy code
macbroom clean --caches            # confirm prompt; or --yolo only after explicit approval

Never run macbroom clean --all --yolo without per-category approval.

4. App updates

bashCopy code
${CLAUDE_PLUGIN_ROOT}/bin/ops-mac update    # updater check — then confirm before applying

After any fix, re-run the relevant probe and show before→after.

Maintenance safety helpers

ops-mac maintenance <helper> exposes bundled source helpers. Without arguments, agent-log-rotate lists logs only. Its copy/truncate rotation is best-effort, not lossless: launchd writers ignore locks, so a line written between the final check and the truncate can be lost; prefer producer-native rotation where available. Machine labels, endpoints, user scope and process allowlists stay in untracked files under ~/.config/claude-ops/. Installing a helper never registers, starts, restarts or kills a job. Use ops-mac maintenance install <helper> --target <path> --expected-sha256 <current> first as a dry-run, then add --apply only after a backup and peer check. Use --expected-sha256 absent only for a new target; prior versions get timestamped backups.

Mobile mode (Rule 7)

If $SSH_CONNECTION/$SSH_CLIENT/$SSH_TTY is set, $OPS_MOBILE=1, or $COLUMNS < 80: drop the boxes/tables, emit 3–8 plain lines, one fact each. Example:

Copy code
mac audit:
security B/100 — firewall OFF.
launchd: 2 dead user daemons.
disk: 8.6 GB safe to clean.
health: machealth probe stuck (TM/iCloud).
fix? /ops:mac fix

When to use this vs other skills