cc-reaper: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

cc-reaper is a shell-based utility that cleans up orphan Claude Code/Codex processes and settled git worktrees that leak memory or disk after sessions end. It uses hooks for low-latency triggers, background agents for guarantees, and manual commands for diagnosis/on-demand cleanup.

Repository Structure

• install.sh — Automated 4-stage installer (shell functions → stop hook → proc-janitor → daemon startup)
• hooks/stop-cleanup-orphans.sh — Claude Code Stop hook; kills orphans using orphan-parent filtering (only truly orphaned processes — reparented to PID 1, or on Linux to the user's systemd --user manager)
• shell/claude-cleanup.sh — Shell functions: claude-cleanup (kill orphans), claude-ram (RAM report), claude-fd (FD usage report), claude-sessions (session list), claude-guard (auto-reaper with RSS/FD threshold + idle detection)
• shell/cc-monitor.sh — Read-only heat attribution monitor (cc-monitor, cc-monitor --apply)
• shell/worktree-janitor.sh — Shared Claude/Codex worktree inventory and gated removal (clean, unheld, no live/recent harness claim, landed, idle); --claims for read-only claim/lease evidence, --session for either harness, and --scheduled for the guarantee layer. The method is in docs/worktree-reclamation.md
• config/worktree-janitor.conf — Cross-device 48-hour/session/schedule policy deployed under ~/.cc-reaper
• shell/reclaim-byproducts.sh — Session scratchpads, anonymous Docker volumes, go build cache, reclaim archives; its own LaunchAgent via --install-launchd (adopted from the skills repository 2026-10-07). The transcript lookup behind the scratchpad liveness rule is one pass, cached under ~/.cc-reaper/state on a corpus fingerprint and bounded by CC_RB_MENTION_BUDGET_SECONDS (default 600); a lookup that does not finish, or whose find or grep errors (status 2 or more, a missing binary, a signal), keeps every directory, writes no cache and no stamp
• shell/resource-watch.sh — also the disk guard: ALERT:disk-low under 60 GB free; under 40 GB the reclaim (worktree-janitor.sh --scheduled, then reclaim-byproducts.sh) started detached as resource-watch.sh --act with a 30-minute cooldown, a single-instance lock (~/.cc-reaper/state/disk-act.lock) and a 90-minute cap after which the next round ends its process tree by pid; under 20 GB ALERT:disk-emergency and the flag ~/.cc-reaper/state/disk-emergency; a GB/h write rate from disk-free-samples.tsv (ALERT:disk-rate over 10, flag disk-rate-high over 20); and reclaim-byproducts.sh --go-cache-cap every run, bounded to 120 s. ALERT:reclaim-stalled (once per stall, alert only) when reclaim-byproducts' last-finished stamp is older than twice its LaunchAgent's StartInterval (CC_RW_RECLAIM_STALL_SECS); with no stamp at all the age is the plist's mtime (else the script's): inside the line one INFO line, over it the same once-only alert; test T19. A round never waits on the act. Each snapshot line carries swap=<gb>GB rate=<gbh>GB/h. Tests: tests/resource-watch.sh (T12-T21), tests/disk-guard.sh
• shell/resource-watch-judge.py — the one judge of resource-watch's log, for a spot-check to import: thresholds are the script's defaults overridden by the installed LaunchAgent's EnvironmentVariables; each judged ALERT marker (load, disk, disk-low, disk-emergency, mem, swap, disk-rate) against the line's own numbers. Read-only. Tests: tests/resource-watch-judge.py (its defaults are pinned to the script's)
• shell/disk-janitor.sh — --check disk guard. Below CC_DJ_ACT_FREE_GB (default 30) it acts; the go build cache age trim (go-build-age) runs on free space under CC_DJ_ACT_LOW_FREE_GB (20), under CC_DJ_GO_BUILD_FREE_GB (35), or a cache over CC_DJ_GO_BUILD_CAP_GB (8), also from --check outside the act. Because the act itself runs only below 30 GB, the effective free-space trigger inside the act is 30 GB, not 20 GB (the 35 GB soft floor is above it, so every act runs the step). It deletes only in CC_DJ_NEW_STEPS_MODE=auto (default spotcheck: logs decision=would-remove), after one bounded (CC_DJ_HOLDER_TIMEOUT_SECONDS, lsof -b) system-wide lsof; a timeout or non-zero lsof deletes nothing. Tests: tests/disk-janitor.sh
• shell/gce-disk-watch.py — reads each GCE CI host's / from the Mac mini (one IAP df -P / ; df -Pi /, the only remote command; per-host 90 s, per-run 240 s) and tells disk-high (used >= 90%, < 2 GiB free, inodes >= 90%) or unreadable (never for a GDW_KNOWN_UNREADABLE host, logged known-unreadable) once per state change, re-alert every 120 min, one recovery line. Shadow (GDW_APPLY=0) logs would alert lines only; apply writes a GCE-DISK ALERT|STILL|RECOVERED log line and a notification, retrying a failed channel alone; nothing goes to an inbox or an event log. Policy config/gce-disk-watch.conf; agent com.cc-reaper.gce-disk-watch (600 s, never started by install). Tests: tests/gce-disk-watch.py
• shell/orbstack-memory-trim.sh — Drops the OrbStack guest's clean caches when its VM process holds over a quarter of RAM; com.cc-reaper.orbstack-memory-trim every 15 min (adopted from stima-api 2026-10-07)
• hooks/worktree-session-end.sh — Thin shared Claude/Codex SessionEnd trigger
• proc-janitor/config.toml — Daemon config with target patterns, whitelist, and grace period settings
• launchd/ — macOS LaunchAgent scripts for zero-dependency background monitoring
• tests/ — Lightweight bash validation scripts (mocked ps/kill for isolated testing)