Skip to content

v0.1.0 — the janitor for an always-on agent CLI

Latest
Latest

Choose a tag to compare

View all tags
@tonydzi tonydzi released this 04 Aug 19:33
· 9 commits to main since this release
v0.1.0
e90647c

Your Mac is not old. It is holding thirty half-dead agent sessions. First tagged release.

One file, Python standard library only. No dependencies, no telemetry, no network.

python3 mac_patrol.py --dry-run     # shows every decision, changes nothing
python3 mac_patrol.py --install     # 30-min schedule (launchd on macOS, cron on Linux)

Measured on one laptop, 4 August 2026

before after
load average 233 27.7
free CPU 4% 68%
open agent sessions 32 6
RAM held by one MCP server class 4.9 GB 0.81 GB

Nothing was reinstalled, nothing was rebooted. The machine was carrying work nobody was waiting for any more.

What is in v0.1.0

  • CPU-delta measurement, never ps %CPU. %CPU is an average over the process's whole lifetime — on a long-lived daemon it is off by any amount you like. We once announced that the system antivirus had been stuck for five days off a reading of 91.4%; two ps -o time= snapshots five seconds apart showed it asleep. Every verdict here is a delta of two snapshots.
  • Class-weighted memory accounting. A watchdog that alarms on "any MCP server over 700 MB" never fires while thirty copies of a 163 MB server quietly eat 4.9 GB. It weighs the class, not the process.
  • Orphan and stale-session detection, with self-chain protection so the patrol cannot kill the session that started it.
  • --dry-run prints every decision and changes nothing — and it is the format we want in bug reports.
  • SKILL.md — the same field procedure our own agents follow, with the traps annotated. Drop it into ~/.claude/skills/mac-patrol/ and your Claude Code can run the cleanup for you.
  • 58 offline tests on fake process snapshots, killing nothing — including a real injected crash, to prove the crash-guard exits 4 rather than masquerading as "found and handled". New in this release: they run on CI (Ubuntu + macOS × Python 3.9/3.11/3.13, plus weekly). Until today the suite existed and nothing ran it.
  • Three safety fixes from an adversarial external review landed before this tag.

Platform

macOS is the target. Linux works (cron + /proc). Windows parses and schedules but has no CPU-delta measurement, so it falls back to the hard 24h session ceiling only — deliberately returning nothing rather than a fake zero.

Honest limit

Every threshold in here was tuned on one machine over one bad week. If it misdiagnoses something on yours, open an issue with the --dry-run output — a disagreement with our thresholds is the most useful bug report we can get.

What's next

Thresholds validated on more than one laptop, Windows CPU-delta, and a wider set of process classes. Every noticeable change ships as its own release, because a janitor that kills the wrong process is worse than no janitor, and you should be able to see exactly what changed between the version you ran last month and this one.

Full Changelog: https://github.com/Palo-Alto-AI-Research-Lab/claude-mac-patrol/commits/v0.1.0

Assets 2
Loading