caproom

Prevent RAM OOM for long-running terminal coding agents, builds, and background jobs — memory caps plus idle-process parking, for macOS, Linux, and Windows.

Why

macOS has no reliable way to cap a process's memory from userspace. A runaway process — a leaking build tool, an AI agent stuck in a loop, a stray find / — has nothing standing between it and system OOM. caproom fills that gap with a host-native polling watchdog that actually enforces a limit on the whole process tree.

What it does (Rust-only v0.9.0)

caproom --limit <mb> -- <command> [args...]
# or explicit subcommand
caproom run --limit 2048 -- npm run build

Single binary bin/caproom-rs (1.2M, target/release/caproom copy) — no bash, no JS wrapper, no PowerShell shim. The 1K-line bash watchdog (bin/caproom), bin/caproom.js, bin/caproom-mcp.js, bin/caproom.ps1, scripts/postinstall.js were removed in f017051 (0.8.1). Install via cargo, brew, or npm (npm unpacks prebuilt caproom-darwin-arm64/x64, caproom-linux-x64, caproom-win32-x64.exe).

Core mechanism:

• Collector: proc_listallpids + proc_pidinfo PROC_PIDTBSDINFO/TASKINFO + proc_pid_rusage ri_phys_footprint (libproc, not ps). Measures phys_footprint (Mach TASK_VM_INFO, Jetsam/Activity Monitor truth) — not RSS. RSS overcounts shared libs. R/S state comes from TASKINFO pti_numrunning, because pbi_status reports SRUN for processes blocked in time.sleep.
• Tree walk: whole process tree per poll (agents keep memory in children — MCP servers, bundler daemons, headless browsers — while parent RSS stays flat). Ancestry walk depth 64, reparented to launchd/init (ppid 1) escapes.
• Parking predicate is_idle_subtree: still_in_tree + footprint >=512KB + !is_session_leader (pid == sid primary, pgid == pid fallback — foreground group never parks) + cpu_delta <0.02 (2% over 500ms window via CpuRing from ri_user_time+ri_system_time delta). Dropped pbi_status S|I gate in 0.8.0 — multithreaded Python/Node reports R while sleeping in time.sleep.
• Escalation: park idle subtrees (SIGSTOP) → resample after 1s → only TERM → grace 5s → KILL if still over effective_limit. effective_limit = limit * (80 + 20*free_pct/15)/100 (free_pct from vm_stat/MemAvailable), so low headroom lowers trigger but doesn't escalate without park.
• Polling-only v1: vm_stat/free_mem_pct every 200ms. dispatch_source_memorypressure event-driven (0% idle) is not built — pressure::try_init_pressure_source() -> false and logs poll fallback 200ms (dispatch unavailable, v1.1 daemon will use GCD source). Deferred to daemon v1.1 single Mach source.
• Docker backend dropped: no --docker/--image in Rust (native only). --pty/--no-intercept-tty/--force-watchdog/init/setup/SAFE_RUN also dropped — they were bash-only.

Install

# from source (requires Rust stable)
cargo install --locked --path crates/cli
# or
cargo install caproom  # once published to crates.io

# Homebrew (tap exists, formula builds from source)
brew tap intelogroup/caproom
brew install caproom

# npm (unpacks prebuilt binaries, no wrapper)
npm install -g caproom
# clean up old global npm shim if you migrated from bash
npm rm -g caproom; nvm use system; hash -r; which caproom # should be ~/.cargo/bin/caproom

Binary: ~/.cargo/bin/caproom v0.9.0, caproom --help prints Memory-cap any command — Rust CLI-first v1.

Usage

# cap a build at 2GB
caproom --limit 2048 -- npm run build
caproom run --limit 2048 -- npm run build

# cap an AI coding agent run at 512MB
caproom --limit 512 -- claude -p "refactor this module"

# inspect trees
caproom freemem                # prints free %
caproom top                    # human table sorted by TREE_MB
caproom top --json             # machine schema 1
caproom top --json --pid 45057 # one subtree
caproom top --json --park-min-mb 1024

# park / wake
caproom park <pid>   # SIGSTOP — pages eligible for reclaim under pressure
caproom wake <pid>   # SIGCONT
caproom status <pid> # ps stat/rss

# calibrate limit from current footprint (24GB->14G, 8GB->4G clamp)
caproom calibrate
caproom calibrate --duration 30

Flags

| Flag | Default | Meaning | |---|---|---| | --limit <mb> | 4096 | memory cap in MB (phys_footprint) | | --interval <sec> | 0.2 | watchdog poll interval | | --grace <sec> | 5 | seconds to wait after SIGTERM before SIGKILL |

On breach: SIGTERM whole tree → wait grace → SIGKILL grace survivors from breach snapshot. Exit 143 if TERM honored, 137 if KILL (same as Docker OOM convention, but now native).

Backends compared (POSIX)

| | Watchdog (bash 0.7.6) | Watchdog (Rust v1) | Watchdog (Windows) | |---|---|---|---| | Measures | RSS of tree | phys_footprint (ri_phys_footprint) | working set | | Children | tree walked each poll | libproc tree walked each poll | tree walked | | Enforcement | TERM → grace → KILL | TERM → grace → KILL | taskkill /T /F | | Race window | bounded by interval | bounded by interval (polling-only; event-driven deferred) | bounded | | Interactive | full tty | full tty | temp-file tail-follow (~50ms) |

Rust is a faster polling loop with better metrics, not yet event-driven.

caproom top — process-tree inventory

Read-only snapshot of every tree you own, sorted by tree footprint.

{ "schema": 1, "ts": 1755950000, "limit_mb_default": 4096,
  "processes": [
    { "pid": 45057, "cmd": "node /tmp/hog.mjs", "tree_rss_kb": 455136, "footprint_kb": 455136,
      "tree_pids": [45057, 45060], "state": "running", "reason_code": "PARK_IDLE|GROWTH_RATE|PRESSURE|NONE",
      "growth_kb_s": 0, "free_pct": 33, "park_candidate": true,
      "reason": "root sleeping + tree_rss 455136KB >= 524288KB park threshold" } ] }

One row per tree root; park_candidate is heuristic (state running + sleeping + footprint ≥ threshold) with reason spelled out.

park / wake — reclaim idle memory without killing

caproom park <pid>        # SIGSTOP — single PID, pages eligible for kernel compressor
caproom park-tree <pid>   # SIGSTOP whole tree (recursive Tree::build) — PID reuse guarded (pid,start)
caproom wake <pid>        # SIGCONT single
caproom wake-tree <pid>   # SIGCONT whole tree

Verified on macOS: parked RSS dropped ~90% (345MB → 37MB) once real pressure hit. No reclaim while system idle/unpressured — rides kernel compressor, doesn't force. Caveat: parked process does zero work while stopped — only park something actually idle (watcher, finished subprocess), never the process an agent is waiting on.

Predicate is_idle_subtree protects: cpu_delta <0.02 (CpuRing 500ms window, first sample assumes busy 1.0 so active watcher not parked on first sight) and is_session_leader (pid == sid primary, pgid == pid fallback) never parks foreground. Tested with real python3 -c "while True: pass" busy vs sleep idle — park_does_not_hang_active_watcher proves.

caproom calibrate — suggest limit

Prints total RAM, free %, top 3 trees footprint, and suggested --limit (60% total, clamp 4G min / 80% max). Migration note old RSS --limit 6144 ≈ footprint ~4.8G (≈80% due shared overcount).

MCP — typed surface

crates/caproom-mcp is hand-rolled serde JSON with strictly typed enums (state: parked|running|zombie, reason_code: PARK_IDLE|GROWTH_RATE|PRESSURE|NONE), no message string. Tools v1 (8): top, park, park_tree, wake, wake_tree, run, freemem, status. Unknown tools return proper JSON-RPC error objects (-32601). watch_* + rmcp deferred to v1.1 with tokio isolated to MCP crate.

Windows

Same run/top/park/wake via cfg(unix)/cfg(windows) guards (cargo check --target x86_64-pc-windows-msvc passes). park/wake are stubs (park not implemented on Windows) — EmptyWorkingSet not wired in Rust v1. Windows watchdog taskkill /T /F for TERM/KILL, no grace, --grace ignored. No Job Object hard cap — Rust is watchdog-only.

Rust port status (current main 0.9.0)

• ✅ phys_footprint via libproc, typed top --json with growth_kb_s/reason_code/free_pct
• ✅ is_idle_subtree ancestry walk + cpu_delta (CpuRing first-sample busy) + is_session_leader (pid==sid + pid==pgid fallback) wired, S|I gate dropped, 28 tests incl. park_does_not_hang_active_watcher
• ✅ R/S via TASKINFO pti_numrunning (pbi_status reports SRUN for sleepers); pid-list buffer grows past 8192 instead of silent truncation
• ✅ growth contextual should_enforce_growth (70% + pressure + <5min breach, 600s for >1MB/s) not bare >200 KB/s; pressure cached hw.memsize OnceLock + free 800ms/200ms
• ✅ park-tree/wake-tree tree-aware + (pid,start_time) reuse guard (pbi_start / /proc/starttime via getsid), is_session_leader fixes Ghostty→tmux conflation
• ✅ MCP: 8 tools, invalid-pid guards (kill(0)/kill(1) rejected), park_tree reuse guard, JSON-RPC error objects, EPIPE-safe writes
• ✅ effective_limit = limit * (80 + 20*free_pct/15)/100 pressure-aware threshold
• ❌ Not yet: dispatch_source_memorypressure event-driven (polling-only v1), rmcp port, daemon+arbiter. See docs/plan-caproom-rust.md for reality vs pitch.

Limitations

• Watchdog has bounded interval race window; for hard guarantee use cgroups outside caproom (Docker dropped in Rust v1).
• Tree walk follows live ppid edges. Daemonized double-fork reparented to 1 escapes by design — prefer missing outside lineage over interfering with user processes.
• Parking only makes pages eligible; kernel compresses lazily under real pressure. Parking 2GB on idle machine may stay ~2GB for hours.

License

MIT