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>
99 lines
3.5 KiB
Markdown
99 lines
3.5 KiB
Markdown
# 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:
|
|
|
|
1. **Audit** — run the module's script (read-only)
|
|
2. **Report** — parse JSON output, present findings as a severity-ranked table
|
|
3. **Recommend** — list available actions grouped by risk
|
|
4. **Consent** — ask user which actions to approve (per-category, per-item for risky)
|
|
5. **Act** — execute only approved actions
|
|
|
|
## Running Audit Scripts
|
|
|
|
All scripts are in `scripts/` and output JSON lines to stdout:
|
|
|
|
```bash
|
|
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
|
|
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
|
|
|
|
1. Run all 5 audit scripts sequentially, collect all JSON findings
|
|
2. Parse and group findings by severity (critical first, then warning, then info)
|
|
3. Present unified report table to the user
|
|
4. **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."
|
|
5. Execute only approved actions
|
|
6. 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
|