Orphan Reaper

npx orphan-reaper scan

The Problem

AI coding agents (Claude Code, Cursor, Copilot) spawn dev servers as child processes. When the agent session ends, these processes become orphans — no parent, no terminal, invisible, burning CPU and RAM forever.

Your bun dev or npm run dev pipeline handles cleanup properly. But agents bypass the pipeline and run individual scripts directly. When the agent exits, there's no orchestrator to clean up.

orphan-reaper finds and kills these orphans. Nothing else.

Install

Usage

orphan-reaper scan              # List orphan processes (don't kill)
orphan-reaper kill              # Kill all orphans (SIGTERM)
orphan-reaper patterns          # Show matched process patterns
orphan-reaper add 'pattern'     # Add a custom pattern
orphan-reaper version           # Show version

Flags

Example

$ orphan-reaper scan
  PID 42381  127MB  node .../storybook dev -p 6006
  PID 42399   33MB  node .../esbuild --service --ping
  PID 51002   89MB  node .../vite preview --port 4173

3 orphan(s), ~249MB total

$ orphan-reaper kill
  killed PID 42381  127MB  node .../storybook dev -p 6006
  killed PID 42399   33MB  node .../esbuild --service --ping
  killed PID 51002   89MB  node .../vite preview --port 4173

Killed 3 process(es), freed ~249MB

How It Works

A process is an orphan if it matches ALL three conditions:

1. Known dev tool pattern — matches one of 21 built-in patterns (storybook, vite, esbuild, next, webpack, etc.)
2. No controlling terminal — tty == "??" means it outlived its parent shell
3. Not the current script — self-exclusion to avoid suicide

Processes with a TTY (your intentional terminal sessions) are never touched. This is the key safety mechanism — POSIX TTY assignment is the only reliable way to distinguish "user is running this" from "an agent left this behind."

Default Patterns

21 patterns covering the most common dev tools:

Custom Patterns

Add project-specific patterns to ~/.orphan-reaper/patterns.conf:

# Add via CLI
orphan-reaper add 'my-custom-dev-server'

# Or edit directly
echo 'my-custom-dev-server' >> ~/.orphan-reaper/patterns.conf

One regex per line. Lines starting with # are comments.

JSON Output

All commands support --json for scripting and tool integration:

$ orphan-reaper scan --json
{"ok": true, "count": 2, "total_rss_mb": 160, "orphans": [
  {"pid": 42381, "rss_mb": 127, "command": "node .../storybook dev -p 6006"},
  {"pid": 42399, "rss_mb": 33, "command": "node .../esbuild --service --ping"}
]}

$ orphan-reaper kill --json
{"ok": true, "killed": 2, "freed_rss_mb": 160, "processes": [...]}

• Success: {"ok": true, ...} with exit code 0
• Error: {"error": "message"} on stderr with exit code 1

Claude Code Plugin

orphan-reaper ships as a Claude Code plugin with automatic cleanup on session end.

Install via marketplace:

claude plugin marketplace add tombelieber/tomstack
claude plugin install orphan-reaper@tomstack

What the plugin does:

Once installed, orphan processes are cleaned up automatically. You never have to think about it again.

How It Compares

Requirements

• macOS or Linux
• Bash 4+
• pgrep, ps, kill (pre-installed on macOS and Linux)
• Python 3 (for JSON escaping, pre-installed on macOS)

Part of tomstack

orphan-reaper is part of tomstack, a Claude Code plugin marketplace by tombelieber.

Other plugins:

• claude-backup — Back up and restore your Claude Code environment