Andrew Yim
f1a973c42d
macOS system health toolkit with 5 audit modules (packages, environment, security, cleanup, resources) and cleanup executor. Fixed bugs from review: - Replace GNU timeout with perl alarm (macOS compatible) - Remove Linux-only ps --sort flag, use portable sort - Add JSON escaping to all audit scripts - Remove redundant classify_size branch Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
3.5 KiB
3.5 KiB
Mac Optimizer
Modular macOS system health toolkit. Runs read-only audits first, then recommends actions with user consent.
Module Routing
| Keywords | Module |
|---|---|
| brew, homebrew, npm, nvm, pip, pyenv, packages, update, outdated | packages |
| path, shell, zshrc, environment, env, config, symlink | environment |
| security, firewall, sip, gatekeeper, filevault, ports, ssh | security |
| cache, cleanup, clean, logs, clutter, disk space, free space, trash | cleanup |
| cpu, memory, ram, disk, battery, processes, resources, slow | resources |
| doctor, audit, health, full check, everything, system check | doctor (all) |
Default to doctor when the request is ambiguous.
Execution Model
Every module follows this flow:
- Audit — run the module's script (read-only)
- Report — parse JSON output, present findings as a severity-ranked table
- Recommend — list available actions grouped by risk
- Consent — ask user which actions to approve (per-category, per-item for risky)
- Act — execute only approved actions
Running Audit Scripts
All scripts are in scripts/ and output JSON lines to stdout:
bash scripts/audit_packages.sh
bash scripts/audit_environment.sh
bash scripts/audit_security.sh
bash scripts/audit_cleanup.sh
bash scripts/audit_resources.sh
Each JSON line has: {"module":"...","severity":"...","finding":"...","action":"...","details":"..."}
Severity levels: critical > warning > info
If a script exits non-zero, report the error and continue with other modules.
Running Cleanup
bash scripts/cleanup_execute.sh --help # See all targets
bash scripts/cleanup_execute.sh --dry-run <targets> # Preview (default)
bash scripts/cleanup_execute.sh --execute <targets> # Actually clean
Always run --dry-run first and show the user what will happen before --execute.
Doctor Mode Workflow
- Run all 5 audit scripts sequentially, collect all JSON findings
- Parse and group findings by severity (critical first, then warning, then info)
- Present unified report table to the user
- STOP and ask: "Which actions would you like me to perform? You can approve by category (e.g., 'update packages and clean caches') or review each item."
- Execute only approved actions
- Present final summary of actions taken
Safety Rules
- Never execute cleanup without explicit user approval
- Always show sizes before deleting anything
- Security module is read-only — present findings and remediation guidance only
- Back up shell configs before modifying:
cp ~/.zshrc ~/.config/mac-optimizer-backups/.zshrc.$(date +%s) - Process deny-list: never suggest killing
kernel_task,launchd,WindowServer,loginwindow,mds,mds_stores,opendirectoryd,coreaudiod,SystemUIServer,Finder,Dock - No sudo by default — if an action needs sudo, state why and ask first
- Docker cleanup uses
docker system prune, never direct file deletion
Report Format
Present findings as a markdown table:
### Critical
| Module | Finding | Recommended Action |
|---|---|---|
| security | Firewall disabled | Enable in System Settings |
### Warning
| Module | Finding | Recommended Action |
|---|---|---|
### Info
| Module | Finding | Recommended Action |
|---|---|---|
Reference Files
- references/packages.md — package manager update strategies and commands
- references/security-checks.md — security benchmarks and remediation guidance
- references/cleanup-targets.md — full list of cleanup paths with risk ratings