pi-breaker

Prevents macOS freezes during pi sessions. Auto-kills runaway processes when memory runs out.

Install

pi install npm:pi-breaker

On first run, it calibrates a baseline for your machine (~10 seconds). After that, it runs silently in the background.

macOS only. Silent no-op on other platforms.

How It Works

Monitor — Polls system health in the background. Classifies into GREEN, YELLOW, ORANGE, or RED.

Watchdog — In confirmed RED, automatically kills the process most likely causing the pressure. No prompts, no questions.

Notification — After a kill, you see a one-line message telling you what was killed and why. That's the only time you'll know it's there.

Commands

Command	Description
/breaker	Crashes prevented since install

Security & System Calls

pi-breaker makes no network requests and reads no environment variables. All system access is local and documented here:

Shell commands (all read-only queries, no mutations):

Command	File	Purpose
sysctl -n kern.ostype	canary.ts	Canary timing benchmark
/usr/bin/true	canary.ts	Canary timing benchmark
sysctl -n vm.swapusage	signals.ts	Read swap usage stats
sysctl -n kern.memorystatus_vm_pressure_level	signals.ts	Read memory pressure level
sysctl -n kern.memorystatus_level	signals.ts	Read memorystatus level
vm_stat	signals.ts	Read VM page statistics
ps -eo pid,rss,comm -r	processes.ts	List processes by memory
ps -eo pid,ppid,etime,comm	monitor.ts	Process tree for watchdog
python3 helpers/footprint.py	processes.ts	Read process footprints via proc_pid_rusage
python3 helpers/footprint_worker.py	worker.ts	Persistent worker for fast footprint queries

Process kills (only pi's own child processes, only in confirmed RED):

Signal	File	Trigger
SIGKILL	monitor.ts	Watchdog auto-kill in confirmed RED zone

Filesystem writes (scoped to ~/.pi/breaker/ only):

What	File	Purpose
~/.pi/breaker/baseline.json	calibration.ts	Persisted canary baseline
~/.pi/breaker/stats.json	index.ts	Kill counter (crashes prevented)
~/.pi/breaker/logs/*.jsonl	logging.ts	Structured logs (auto-GC after 3 days)

Development

npm install
npm test

License

MIT