pi-breaker

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

Package details

extension

Install pi-breaker from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-breaker

Pi manifest JSON

{
  "extensions": [
    "./extensions/index.ts"
  ]
}

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

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

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.

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.

Command	Description
`/breaker`	Crashes prevented since install

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)

npm install
npm test

MIT