# Octopusgarage Heat Guard

> Operate and diagnose macOS system health — auto-clean leaked agent shells + zombies, snapshot CPU/memory/disk pressure, and surface anomalies for notify-and-confirm termination. Use when the machine is hot/slow, to check what's hogging CPU/memory/disk, or as a periodic guardian tick.

- Skill: `octopusgarage/octopusgarage-heat-guard` (Agent Skill, multi-file: 20 files)
- Install (CLI): `npx skillmds@latest add octopusgarage/octopusgarage-heat-guard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/octopusgarage/octopusgarage-heat-guard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: OctopusGarage (https://skillmd.com/u/octopusgarage)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/octopusgarage/octopusgarage-heat-guard

---


# octopusgarage-heat-guard

A macOS system-health guardian. Each invocation is one **tick**: run the
deterministic script (which already auto-cleaned safe junk), then YOU (the AI)
review the remaining `candidates`, and notify-and-confirm before terminating
anything ambiguous. How this skill is scheduled is the operator's concern.

## Setup
```
cd "$SKILL_DIR/scripts" && uv sync --quiet
```

## Tick workflow
1. Run the scan (auto-clean happens inside; it only kills zombies + leaked shells):
   ```
   uv run python -m heat_guard.cli scan
   ```
   Use `--dry-run` to observe without killing.
2. Read the JSON. If `candidates` is empty and `system_flags` is empty → report
   "healthy" and stop. This is the cheap common path.
3. For each candidate, judge **expected vs anomalous** using its `command`,
   `cpu_time_s`, `etime_s`, `pcpu`, `rss_mb`, `tripped`, and the decision state in
   `~/.heat-guard/state.json`:
   - Known-good (a build/encode you recognize, an agent session the user already
     acknowledged, THIS session or sibling loop/bot sessions) → skip.
   - Previously marked keep/snooze and still valid → skip.
   - Genuinely anomalous and unacknowledged → notify.
   If you need a candidate's working directory or owner to judge it (e.g. which project an agent session belongs to), fetch it on demand: `lsof -a -p <pid> -d cwd` and `ps -o user= -p <pid>`.
4. **Notify + confirm** (never auto-kill): send the user a concise message —
   what, why it's suspicious, your recommendation — and ask them to confirm
   termination. Prefer the live Telegram channel (`reply`); if unavailable, use
   the fallback in `heat_guard/telegram.py`. Record the candidate as `pending`
   in `~/.heat-guard/state.json`.
5. On the user's reply: confirm → terminate (SIGTERM, then SIGKILL if it
   survives) and report; keep/snooze → record it so you stop nagging.

## Hard rules
- The script NEVER kills anything but zombies + leaked shells. You NEVER kill a
  candidate without explicit user confirmation.
- Never touch this session or its ancestors (the script already protects them).
- See `references/triage-guidance.md` for how to judge anomalies and message copy.