caproom 0.2.0 → 0.3.1

package/README.md

@@ -58,6 +58,16 @@ Env var overrides: `CAPROOM_LIMIT_MB`, `CAPROOM_IMAGE`, `CAPROOM_INTERVAL`, `CAP
 
 On cap breach, the watchdog backend sends `SIGTERM` first and waits `--grace` seconds before `SIGKILL`. If the process exits cleanly during the grace window, `caproom` propagates its real exit code; only a hard `SIGKILL` (process ignored `SIGTERM`, or grace ran out) reports `137` (same convention as Docker's own OOM-kill exit code, which the docker backend always uses on breach since Docker itself sends the kill).
 
+## init — auto-cap a command on every launch
+
+For a command you always want capped (e.g. an AI coding agent), don't type the wrapper every time — bake it into your shell so a new terminal tab is capped automatically:
+
+```bash
+caproom init claude --limit 6144 --grace 10 >> ~/.zshrc && source ~/.zshrc
+```
+
+This appends a shell function that wraps `claude` through the watchdog backend (host-native — no Docker isolation, so the wrapped command keeps its normal filesystem/auth/PATH access) and an alias so plain `claude` picks it up. Per-shell override without editing the rc file: `CAPROOM_LIMIT_MB=8192 claude ...`. Works for any command, not just `claude` — `caproom init npm --limit 2048` wraps `npm` the same way.
+
 ## park / wake — reclaim idle memory without killing
 
 Long-running agent sessions accumulate subprocesses that go idle but stay resident — old file watchers, finished tool-call children, stale servers. Killing them loses state; leaving them wastes RAM. `caproom park` freezes instead:
@@ -77,6 +87,10 @@ No daemon, no tracking file, no dependency — just `SIGSTOP`/`SIGCONT` wrapped
 
 **Caveat**: a parked process does zero work while stopped — no CPU, no I/O, no timers firing. Only park something actually idle (a background watcher, a finished subprocess kept around for reuse) — never park the process an agent is actively waiting on a response from, or you'll hang the agent, not save it memory.
 
+## What it never touches
+
+caproom only watches OS-level RSS and sends signals (`SIGTERM`/`SIGKILL`/`SIGSTOP`/`SIGCONT`). The watchdog backend runs the wrapped command as a direct child with stdin/stdout/stderr passed straight through — no pipe, no buffering, no interception. The Docker backend passes stdio through the same way (`docker run -i`). caproom never reads, modifies, or truncates anything the wrapped process reads or writes — including an AI agent's own conversation/context stream. It manages RAM headroom only, nothing else.
+
 ## Limitations
 
 - Docker backend mounts `$PWD` into the container at `/work` and runs there — paths outside `$PWD` aren't visible to the command.

package/bin/caproom

@@ -10,11 +10,15 @@
 set -euo pipefail
 
 usage() {
-  cat >&2 << 'EOF'
+  local stream=/dev/stderr
+  local code=1
+  if [[ "${1:-}" == "help" ]]; then stream=/dev/stdout; code=0; fi
+  cat >"$stream" << 'EOF'
 usage: caproom [--limit <mb>] [--image <docker-image>] [--interval <sec>] -- <command> [args...]
        caproom park <pid>
        caproom wake <pid>
        caproom status <pid>
+       caproom init <command> [--limit <mb>] [--grace <sec>]
 
   --limit <mb>     memory cap in MB (default: 4096)
   --image <name>   docker image to run the command in, when using the docker
@@ -35,6 +39,12 @@ becomes eligible for compression under system memory pressure. `caproom wake
 Any agent can call these directly — they're just SIGSTOP/SIGCONT, no daemon,
 no tracking file required.
 
+init <command> — print a shell snippet that auto-caps <command> on every
+invocation, so a new terminal tab is capped with no extra typing. Append the
+output to your shell rc (~/.zshrc, ~/.bashrc):
+
+  caproom init claude >> ~/.zshrc && source ~/.zshrc
+
 env vars (override flags): CAPROOM_LIMIT_MB, CAPROOM_IMAGE, CAPROOM_INTERVAL, CAPROOM_GRACE
 
 examples:
@@ -42,8 +52,33 @@ examples:
   caproom --limit 512 -- claude --dangerously-skip-permissions -p "task"
   caproom park 12345
   caproom wake 12345
+  caproom init claude --limit 6144 --grace 10
+EOF
+  exit "$code"
+}
+
+cmd_init() {
+  local target="${1:-}"
+  [[ -z "$target" ]] && { echo "usage: caproom init <command> [--limit <mb>] [--grace <sec>]" >&2; exit 1; }
+  shift
+  local limit=4096
+  local grace=5
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --limit) limit="$2"; shift 2 ;;
+      --grace) grace="$2"; shift 2 ;;
+      *) echo "caproom: unknown init flag $1" >&2; exit 1 ;;
+    esac
+  done
+  local fn="${target}_capped"
+  cat << EOF
+# caproom: auto-cap '$target' — added by 'caproom init $target'
+# override per-shell: CAPROOM_LIMIT_MB=8192 $target ...
+$fn() {
+  command caproom --limit "\${CAPROOM_LIMIT_MB:-$limit}" --force-watchdog --grace "\${CAPROOM_GRACE:-$grace}" -- command $target "\$@"
+}
+alias $target=$fn
 EOF
-  exit 1
 }
 
 cmd_park() {
@@ -72,6 +107,8 @@ case "${1:-}" in
   park) shift; cmd_park "$@"; exit 0 ;;
   wake) shift; cmd_wake "$@"; exit 0 ;;
   status) shift; cmd_status "$@"; exit 0 ;;
+  init) shift; cmd_init "$@"; exit 0 ;;
+  help|-h|--help) usage help ;;
 esac
 
 LIMIT_MB="${CAPROOM_LIMIT_MB:-4096}"
@@ -88,7 +125,7 @@ while [[ $# -gt 0 ]]; do
     --grace) GRACE="$2"; shift 2 ;;
     --force-watchdog) FORCE_WATCHDOG=1; shift ;;
     --) shift; break ;;
-    -h|--help) usage ;;
+    -h|--help) usage help ;;
     *) break ;;
   esac
 done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caproom",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Memory-cap any command (AI coding agents, builds, background jobs) on macOS/Linux — real enforcement via Docker cgroups or a polling watchdog, plus park/wake to reclaim idle process memory without killing.",
   "bin": {
     "caproom": "bin/caproom"