cleanup-orphans 0.1.1__tar.gz

cleanup_orphans-0.1.1/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.3
+Name: cleanup-orphans
+Version: 0.1.1
+Summary: Detect and safely terminate orphaned AI agent processes (Cursor, agy, Claude, Codex)
+Keywords: agent,orphan,process,cleanup
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: click>=8.5.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: structlog-config>=0.15.0
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/iloveitaly/python-cleanup-orphans
+Description-Content-Type: text/markdown
+
+[![Release Notes](https://img.shields.io/github/release/iloveitaly/python-cleanup-orphans)](https://github.com/iloveitaly/python-cleanup-orphans/releases)
+[![Downloads](https://static.pepy.tech/badge/cleanup-orphans/month)](https://pepy.tech/project/cleanup-orphans)
+![GitHub CI Status](https://github.com/iloveitaly/python-cleanup-orphans/actions/workflows/build_and_publish.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# Clean Up Orphaned AI Agent Processes
+
+I run AI coding tools all day—Cursor, agy, Claude, Codex—and they inevitably leave behind orphaned background workers, zombie MCP servers, and suspended terminal sessions reparented to launchd that chew through RAM and CPU. This CLI scans for abandoned agent processes, lays them out in an interactive fzf interface, and cleanly shuts them down along with their entire descendant process tree.
+
+## Installation
+
+```bash
+uv tool install cleanup-orphans
+```
+
+Or add to an existing project:
+
+```bash
+uv add cleanup-orphans
+```
+
+## Usage
+
+Launch interactive multi-select via `fzf`:
+
+```bash
+cleanup-orphans
+```
+
+Print candidates in a dry-run table:
+
+```bash
+cleanup-orphans --list
+```
+
+Terminate all identified candidates after confirmation:
+
+```bash
+cleanup-orphans --kill-all
+```
+
+## Features
+
+- Scans for reparented Cursor agent workers (PPID 1)
+- Flags suspended or stopped agent sessions (STAT T)
+- Detects runaway agent sessions exceeding CPU thresholds
+- Finds detached headless Claude CLI streaming processes
+- Identifies orphaned OpenAI Codex CLI instances
+- Recursively tracks and terminates child MCP servers, language servers, and watchdogs
+- Graceful termination escalating from SIGTERM to SIGKILL
+- Interactive terminal UI using `fzf` with a fixed column header row
+
+## Comparison
+
+Existing utilities fall into two camps: non-interactive batch daemons targeted at specific runtimes (`TheStack-ai/zclean`, `kojott/claude-gc`), or general-purpose process killers (`fkill`, shell wrappers) that lack process-lineage and AI-tool context.
+
+`cleanup-orphans` combines AI ecosystem detection with interactive triage:
+
+| Feature | `zclean` / `claude-gc` | `fkill` / `fzf` snippets | `cleanup-orphans` |
+|---|---|---|---|
+| Targets AI agent ecosystem | Yes (MCP, Claude) | No (all system procs) | Yes (Cursor workers, agy, Claude, Codex, MCP trees) |
+| Interactive TUI triage | No (batch / cron only) | Yes (`fkill` / `fzf`) | Yes (`fzf` multi-select with `Ctrl-A` and confirmation) |
+| Sorting | Unsorted / Name | Fuzzy search rank | Oldest-first by elapsed wall-clock time |
+| Descendant cascade reaping | Basic | No | Full tree traversal (reaps child MCPs and watchdogs) |
+| Working directory context | No | No | Yes (macOS `libproc` extraction of exact repo/worktree) |
+| Job-control suspensions (`STAT T`) | No | No | Yes (identifies backgrounded `Ctrl-Z` sessions) |
+| Human-readable metrics | Raw memory | Raw PID / Name | Formatted age (`15d 1h ago`) and CPU (`3h 18m`) |
+
+## [MIT License](LICENSE.md)
+
+---
+
+*This project was created from [iloveitaly/python-package-template](https://github.com/iloveitaly/python-package-template)*

cleanup_orphans-0.1.1/README.md

@@ -0,0 +1,73 @@
+[![Release Notes](https://img.shields.io/github/release/iloveitaly/python-cleanup-orphans)](https://github.com/iloveitaly/python-cleanup-orphans/releases)
+[![Downloads](https://static.pepy.tech/badge/cleanup-orphans/month)](https://pepy.tech/project/cleanup-orphans)
+![GitHub CI Status](https://github.com/iloveitaly/python-cleanup-orphans/actions/workflows/build_and_publish.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# Clean Up Orphaned AI Agent Processes
+
+I run AI coding tools all day—Cursor, agy, Claude, Codex—and they inevitably leave behind orphaned background workers, zombie MCP servers, and suspended terminal sessions reparented to launchd that chew through RAM and CPU. This CLI scans for abandoned agent processes, lays them out in an interactive fzf interface, and cleanly shuts them down along with their entire descendant process tree.
+
+## Installation
+
+```bash
+uv tool install cleanup-orphans
+```
+
+Or add to an existing project:
+
+```bash
+uv add cleanup-orphans
+```
+
+## Usage
+
+Launch interactive multi-select via `fzf`:
+
+```bash
+cleanup-orphans
+```
+
+Print candidates in a dry-run table:
+
+```bash
+cleanup-orphans --list
+```
+
+Terminate all identified candidates after confirmation:
+
+```bash
+cleanup-orphans --kill-all
+```
+
+## Features
+
+- Scans for reparented Cursor agent workers (PPID 1)
+- Flags suspended or stopped agent sessions (STAT T)
+- Detects runaway agent sessions exceeding CPU thresholds
+- Finds detached headless Claude CLI streaming processes
+- Identifies orphaned OpenAI Codex CLI instances
+- Recursively tracks and terminates child MCP servers, language servers, and watchdogs
+- Graceful termination escalating from SIGTERM to SIGKILL
+- Interactive terminal UI using `fzf` with a fixed column header row
+
+## Comparison
+
+Existing utilities fall into two camps: non-interactive batch daemons targeted at specific runtimes (`TheStack-ai/zclean`, `kojott/claude-gc`), or general-purpose process killers (`fkill`, shell wrappers) that lack process-lineage and AI-tool context.
+
+`cleanup-orphans` combines AI ecosystem detection with interactive triage:
+
+| Feature | `zclean` / `claude-gc` | `fkill` / `fzf` snippets | `cleanup-orphans` |
+|---|---|---|---|
+| Targets AI agent ecosystem | Yes (MCP, Claude) | No (all system procs) | Yes (Cursor workers, agy, Claude, Codex, MCP trees) |
+| Interactive TUI triage | No (batch / cron only) | Yes (`fkill` / `fzf`) | Yes (`fzf` multi-select with `Ctrl-A` and confirmation) |
+| Sorting | Unsorted / Name | Fuzzy search rank | Oldest-first by elapsed wall-clock time |
+| Descendant cascade reaping | Basic | No | Full tree traversal (reaps child MCPs and watchdogs) |
+| Working directory context | No | No | Yes (macOS `libproc` extraction of exact repo/worktree) |
+| Job-control suspensions (`STAT T`) | No | No | Yes (identifies backgrounded `Ctrl-Z` sessions) |
+| Human-readable metrics | Raw memory | Raw PID / Name | Formatted age (`15d 1h ago`) and CPU (`3h 18m`) |
+
+## [MIT License](LICENSE.md)
+
+---
+
+*This project was created from [iloveitaly/python-package-template](https://github.com/iloveitaly/python-package-template)*

cleanup_orphans-0.1.1/cleanup_orphans/__init__.py

@@ -0,0 +1,3 @@
+from .version import __version__
+
+__all__ = ["__version__"]

cleanup_orphans-0.1.1/cleanup_orphans/cli.py

@@ -0,0 +1,72 @@
+"""CLI entrypoint for cleanup-orphans."""
+
+import click
+from structlog_config import configure_logger
+
+from .fzf import select_with_fzf
+from .killer import kill_pids
+from .scanner import Candidate, find_candidates
+from .version import __version__
+
+log = configure_logger()
+
+
+def _print_table(candidates: list[Candidate]) -> None:
+    header = f"{'PID':<7} {'PPID':<7} {'CATEGORY':<14} {'REASON':<28} {'AGE':<14} {'STARTED':<15} {'CPU':<9} {'DETAIL'}"
+    click.echo(header)
+    click.echo("-" * 135)
+
+    for c in candidates:
+        click.echo(
+            f"{c.pid:<7} {c.ppid:<7} {c.category:<14} {c.reason:<28} {c.age:<14} {c.started:<15} {c.cpu:<9} {c.detail}"
+        )
+
+    click.echo("-" * 135)
+    click.echo(f"Total candidates: {len(candidates)}")
+
+
+@click.command()
+@click.version_option(version=__version__)
+@click.option(
+    "--list",
+    "list_only",
+    is_flag=True,
+    help="List candidates in table format (dry-run)",
+)
+@click.option(
+    "--kill-all", is_flag=True, help="Kill all candidates with confirmation prompt"
+)
+def cli(list_only: bool, kill_all: bool) -> None:
+    """Detect and safely terminate orphaned AI agent processes.
+
+    Default mode opens an interactive fzf selector.
+    """
+    candidates = find_candidates()
+    if not candidates:
+        click.echo("No orphaned or rogue AI processes found.")
+        return
+
+    if list_only:
+        _print_table(candidates)
+        return
+
+    if kill_all:
+        _print_table(candidates)
+        if click.confirm(f"\nKill all {len(candidates)} candidates?", default=False):
+            kill_pids([c.pid for c in candidates])
+        else:
+            click.echo("Aborted.")
+        return
+
+    # default: interactive fzf selection
+    selected_pids = select_with_fzf(candidates)
+    if not selected_pids:
+        click.echo("Aborted. No processes selected.")
+        return
+
+    if click.confirm(
+        f"\nKill {len(selected_pids)} selected process(es)?", default=False
+    ):
+        kill_pids(selected_pids)
+    else:
+        click.echo("Aborted.")

cleanup_orphans-0.1.1/cleanup_orphans/fzf.py

@@ -0,0 +1,56 @@
+"""Interactive fzf-based process selection."""
+
+import subprocess
+import sys
+
+from .scanner import Candidate
+
+
+def select_with_fzf(candidates: list[Candidate]) -> list[int]:
+    """Present candidates in fzf multi-select and return selected PIDs."""
+    # column header shown as a fixed non-selectable line in fzf
+    header = (
+        f"{'PID':<7} | {'TYPE':<14} | {'REASON':<28} | {'AGE':<12} "
+        f"| {'STARTED':<15} | {'CPU':<8} | DETAIL"
+    )
+
+    lines = [header]
+    for c in candidates:
+        line = (
+            f"{c.pid:<7} | {c.category:<14} | {c.reason:<28} | {c.age:<12} "
+            f"| {c.started:<15} | {c.cpu:<8} | {c.detail}"
+        )
+        lines.append(line)
+
+    fzf_input = "\n".join(lines)
+    try:
+        proc = subprocess.Popen(
+            [
+                "fzf",
+                "-m",
+                "--layout=reverse",
+                "--no-sort",
+                # first line of input is the column header
+                "--header-lines=1",
+                "--header=TAB: select/deselect | Ctrl-A: toggle all | ENTER: kill selected | ESC: quit",
+                "--bind=ctrl-a:toggle-all",
+            ],
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            text=True,
+        )
+        stdout, _ = proc.communicate(input=fzf_input)
+
+        if proc.returncode != 0:
+            return []
+
+        selected_pids = []
+        for line in stdout.strip().splitlines():
+            pid_str = line.split("|")[0].strip()
+            if pid_str.isdigit():
+                selected_pids.append(int(pid_str))
+
+        return selected_pids
+    except FileNotFoundError:
+        print("Error: fzf is not installed or not in PATH.", file=sys.stderr)
+        sys.exit(1)

cleanup_orphans-0.1.1/cleanup_orphans/killer.py

@@ -0,0 +1,75 @@
+"""Process termination with SIGTERM -> SIGKILL escalation."""
+
+import os
+import signal
+import subprocess
+import time
+
+import structlog
+
+log = structlog.get_logger()
+
+
+def _expand_descendants(pids: list[int]) -> list[int]:
+    """Find all recursive child processes so no orphans are left behind."""
+    all_pids = set(pids)
+    out = subprocess.check_output(["ps", "-axo", "pid,ppid"]).decode("utf-8")
+
+    pairs: list[tuple[int, int]] = []
+    for line in out.strip().splitlines()[1:]:
+        parts = line.strip().split()
+        if len(parts) >= 2 and parts[0].isdigit() and parts[1].isdigit():
+            pairs.append((int(parts[0]), int(parts[1])))
+
+    added = True
+    while added:
+        added = False
+        for pid, ppid in pairs:
+            if ppid in all_pids and pid not in all_pids:
+                all_pids.add(pid)
+                added = True
+
+    return sorted(all_pids)
+
+
+def kill_pids(pids: list[int]) -> None:
+    """Send SIGTERM to pids (plus descendants), escalating to SIGKILL after 1s."""
+    if not pids:
+        return
+
+    targets = _expand_descendants(pids)
+    if len(targets) > len(pids):
+        extra = len(targets) - len(pids)
+        log.info(
+            "expanding targets", selected=len(pids), children=extra, total=len(targets)
+        )
+
+    log.info("sending SIGTERM", pids=targets)
+    for pid in targets:
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except ProcessLookupError:
+            pass
+        except PermissionError:
+            log.warning("permission denied", pid=pid)
+
+    time.sleep(1.0)
+
+    # check for survivors and escalate
+    still_alive = []
+    for pid in targets:
+        try:
+            os.kill(pid, 0)
+            still_alive.append(pid)
+        except OSError:
+            pass
+
+    if still_alive:
+        log.info("escalating to SIGKILL", pids=still_alive)
+        for pid in still_alive:
+            try:
+                os.kill(pid, signal.SIGKILL)
+            except OSError:
+                pass
+
+    log.info("kill complete", pids=targets)

cleanup_orphans-0.1.1/cleanup_orphans/process.py

@@ -0,0 +1,149 @@
+"""Process info helpers: cwd lookup, time/cpu parsing, and formatting."""
+
+import contextlib
+import ctypes
+import ctypes.util
+import os
+import subprocess
+
+
+def get_current_process_tree() -> set[int]:
+    """Return PIDs in our own process lineage so we never kill ourselves."""
+    pids = set()
+    pid = os.getpid()
+
+    while pid > 1:
+        pids.add(pid)
+        try:
+            out = (
+                subprocess.check_output(["ps", "-o", "ppid=", "-p", str(pid)])
+                .decode()
+                .strip()
+            )
+            pid = int(out)
+        except (subprocess.SubprocessError, ValueError):
+            break
+
+    return pids
+
+
+def parse_cpu_minutes(cputime: str) -> float:
+    """Parse BSD ps cputime (minutes:seconds.hundredths) into float minutes."""
+    parts = cputime.split(":")
+
+    if len(parts) == 2:
+        return float(parts[0]) + float(parts[1]) / 60.0
+    elif len(parts) == 3:
+        # hours:minutes:seconds
+        return float(parts[0]) * 60.0 + float(parts[1]) + float(parts[2]) / 60.0
+
+    return 0.0
+
+
+def parse_elapsed_seconds(etime: str) -> int:
+    """Convert BSD etime ([[dd-]hh:]mm:ss) into integer seconds."""
+    days, hours, mins, secs = 0, 0, 0, 0
+
+    if "-" in etime:
+        day_part, rest = etime.split("-", 1)
+        days = int(day_part)
+        time_parts = rest.split(":")
+    else:
+        time_parts = etime.split(":")
+
+    if len(time_parts) == 3:
+        hours, mins, secs = map(int, time_parts)
+    elif len(time_parts) == 2:
+        mins, secs = map(int, time_parts)
+    elif len(time_parts) == 1:
+        secs = int(time_parts[0])
+
+    return days * 86_400 + hours * 3_600 + mins * 60 + secs
+
+
+def format_elapsed(etime: str) -> str:
+    """Convert BSD etime ([[dd-]hh:]mm:ss) into a human-readable age string."""
+    days, hours, mins, secs = 0, 0, 0, 0
+
+    if "-" in etime:
+        day_part, rest = etime.split("-", 1)
+        days = int(day_part)
+        time_parts = rest.split(":")
+    else:
+        time_parts = etime.split(":")
+
+    if len(time_parts) == 3:
+        hours, mins, secs = map(int, time_parts)
+    elif len(time_parts) == 2:
+        mins, secs = map(int, time_parts)
+    elif len(time_parts) == 1:
+        secs = int(time_parts[0])
+
+    if days > 0:
+        return f"{days}d {hours}h ago"
+    if hours > 0:
+        return f"{hours}h {mins}m ago"
+    if mins > 0:
+        return f"{mins}m ago"
+    return f"{secs}s ago"
+
+
+def format_cpu(cputime: str) -> str:
+    """Convert BSD ps cputime into human-readable form."""
+    parts = cputime.split(":")
+
+    if len(parts) == 2:
+        m = int(parts[0])
+        s = float(parts[1])
+        if m >= 60:
+            return f"{m // 60}h {m % 60}m"
+        if m > 0:
+            return f"{m}m {int(s)}s"
+        return f"{s:.1f}s"
+    elif len(parts) == 3:
+        h = int(parts[0])
+        m = int(parts[1])
+        return f"{h}h {m}m"
+
+    return f"{float(parts[0]):.1f}s"
+
+
+# C-level libproc wrapper for fast process cwd retrieval on macOS
+_libproc = None
+with contextlib.suppress(OSError):
+    _libproc_path = ctypes.util.find_library("proc")
+    if _libproc_path:
+        _libproc = ctypes.CDLL(_libproc_path)
+        _libproc.proc_pidinfo.argtypes = [
+            ctypes.c_int,
+            ctypes.c_int,
+            ctypes.c_uint64,
+            ctypes.c_void_p,
+            ctypes.c_int,
+        ]
+        _libproc.proc_pidinfo.restype = ctypes.c_int
+
+
+def get_process_cwd(pid: int) -> str:
+    """Query current working directory using macOS libproc (PROC_PIDVNODEPATHINFO = 9)."""
+    if not _libproc:
+        return ""
+
+    with contextlib.suppress(OSError, ValueError):
+        buf = ctypes.create_string_buffer(2_352)
+        # flavor 9 = PROC_PIDVNODEPATHINFO
+        ret = _libproc.proc_pidinfo(pid, 9, 0, buf, ctypes.sizeof(buf))
+        if ret <= 0:
+            return ""
+
+        # offset 152 is char vip_path[1024] inside pvi_cdir
+        path_bytes = buf.raw[152 : 152 + 1_024]
+        null_idx = path_bytes.find(b"\x00")
+        if null_idx != -1:
+            path_bytes = path_bytes[:null_idx]
+
+        path_str = path_bytes.decode("utf-8", errors="replace").strip()
+        if path_str:
+            return path_str.replace(os.path.expanduser("~"), "~")
+
+    return ""

cleanup_orphans-0.1.1/cleanup_orphans/scanner.py

@@ -0,0 +1,233 @@
+"""Scan running processes to find orphaned AI agent candidates."""
+
+import os
+import subprocess
+
+from pydantic import BaseModel
+
+from .process import (
+    format_cpu,
+    format_elapsed,
+    get_current_process_tree,
+    get_process_cwd,
+    parse_cpu_minutes,
+    parse_elapsed_seconds,
+)
+
+
+class Candidate(BaseModel):
+    pid: int
+    ppid: int
+    category: str
+    reason: str
+    cpu: str
+    age: str
+    elapsed_seconds: int
+    started: str
+    cwd: str
+    detail: str
+
+
+class RawProcess(BaseModel):
+    pid: int
+    ppid: int
+    stat: str
+    etime: str
+    cputime: str
+    started: str
+    cmd: str
+
+
+def _parse_process_list() -> list[RawProcess]:
+    """Parse `ps` output into structured process records."""
+    out = subprocess.check_output(
+        ["ps", "-axo", "pid,ppid,stat,etime,cputime,lstart,command"]
+    ).decode("utf-8")
+
+    processes: list[RawProcess] = []
+    for line in out.splitlines()[1:]:
+        parts = line.strip().split(None, 10)
+        if len(parts) < 11:
+            continue
+
+        pid_s, ppid_s, stat, etime, cputime, _day, month, date, time_str, _year, cmd = (
+            parts
+        )
+        processes.append(
+            RawProcess(
+                pid=int(pid_s),
+                ppid=int(ppid_s),
+                stat=stat,
+                etime=etime,
+                cputime=cputime,
+                started=f"{month} {date} {time_str[:5]}",
+                cmd=cmd,
+            )
+        )
+
+    return processes
+
+
+def _build_candidate(
+    proc: RawProcess, category: str, reason: str, detail: str, cwd: str
+) -> Candidate:
+    return Candidate(
+        pid=proc.pid,
+        ppid=proc.ppid,
+        category=category,
+        reason=reason,
+        cpu=format_cpu(proc.cputime),
+        age=format_elapsed(proc.etime),
+        elapsed_seconds=parse_elapsed_seconds(proc.etime),
+        started=proc.started,
+        cwd=cwd,
+        detail=detail,
+    )
+
+
+def _check_cursor_worker(proc: RawProcess) -> Candidate | None:
+    """Cursor agent workers reparented to launchd (PPID 1) are orphans."""
+    if (
+        "cursor-agent" not in proc.cmd
+        or "worker start" not in proc.cmd
+        or proc.ppid != 1
+    ):
+        return None
+
+    ws = ""
+    if "--worker-dir" in proc.cmd:
+        ws = proc.cmd.split("--worker-dir")[1].strip().split()[0]
+        ws = ws.replace(os.path.expanduser("~"), "~")
+
+    cwd = get_process_cwd(proc.pid)
+    return _build_candidate(
+        proc, "cursor-agent", "Reparented to launchd (PPID 1)", ws or cwd, cwd or ws
+    )
+
+
+def _check_agy(proc: RawProcess) -> Candidate | None:
+    """AGY sessions that are orphaned, suspended, or consuming excessive CPU."""
+    is_agy = "agy " in proc.cmd or proc.cmd.endswith("agy")
+    if not is_agy:
+        return None
+
+    cwd = get_process_cwd(proc.pid)
+    detail = f"[{cwd}] {proc.cmd[:50]}" if cwd else proc.cmd[:60]
+
+    if proc.ppid == 1:
+        return _build_candidate(
+            proc, "agy", "Reparented to launchd (PPID 1)", detail, cwd
+        )
+    if "T" in proc.stat:
+        return _build_candidate(
+            proc, "agy", f"Suspended (STAT {proc.stat})", detail, cwd
+        )
+    # 8 hours of CPU is excessive for any single agent session
+    if parse_cpu_minutes(proc.cputime) > 480:
+        return _build_candidate(proc, "agy", "High CPU usage", detail, cwd)
+
+    return None
+
+
+def _is_codex_process(cmd: str) -> bool:
+    return "codex " in cmd or cmd.endswith("codex") or "codex-code-mode-host" in cmd
+
+
+def _check_codex(proc: RawProcess) -> Candidate | None:
+    """Codex CLI processes that are orphaned, suspended, or consuming excessive CPU."""
+    if not _is_codex_process(proc.cmd):
+        return None
+
+    cwd = get_process_cwd(proc.pid)
+    detail = f"[{cwd}] {proc.cmd[:50]}" if cwd else proc.cmd[:60]
+
+    if proc.ppid == 1:
+        return _build_candidate(
+            proc, "codex", "Reparented to launchd (PPID 1)", detail, cwd
+        )
+    if "T" in proc.stat:
+        return _build_candidate(
+            proc, "codex", f"Suspended (STAT {proc.stat})", detail, cwd
+        )
+    if parse_cpu_minutes(proc.cputime) > 480:
+        return _build_candidate(proc, "codex", "High CPU usage", detail, cwd)
+
+    return None
+
+
+def _check_claude_stream(proc: RawProcess) -> Candidate | None:
+    """Detached headless Claude stream-json processes."""
+    if "claude " not in proc.cmd or "--output-format stream-json" not in proc.cmd:
+        return None
+
+    cwd = get_process_cwd(proc.pid)
+    detail = f"[{cwd}] {proc.cmd[:50]}" if (cwd and cwd != "/") else proc.cmd[:60]
+    return _build_candidate(proc, "claude", "Detached headless stream", detail, cwd)
+
+
+# ordered list of detection heuristics
+_CHECKERS = [
+    _check_cursor_worker,
+    _check_codex,
+    _check_agy,
+    _check_claude_stream,
+]
+
+
+def _collect_descendants(
+    candidate_pids: set[int],
+    candidates_by_pid: dict[int, Candidate],
+    all_processes: list[RawProcess],
+) -> list[Candidate]:
+    """Recursively find child processes of candidates (e.g. MCP servers spawned by cursor workers)."""
+    descendants: list[Candidate] = []
+    added = True
+
+    while added:
+        added = False
+        for proc in all_processes:
+            if proc.ppid not in candidate_pids or proc.pid in candidate_pids:
+                continue
+
+            parent = candidates_by_pid.get(proc.ppid)
+            parent_label = parent.category if parent else "unknown"
+            reason = f"Child of {parent_label} ({proc.ppid})"
+
+            cwd = get_process_cwd(proc.pid)
+            detail = f"[{cwd}] {proc.cmd[:45]}" if cwd else proc.cmd[:60]
+            child = _build_candidate(proc, "child", reason, detail, cwd)
+            descendants.append(child)
+            # register so grandchildren can resolve their parent too
+            candidates_by_pid[proc.pid] = child
+            candidate_pids.add(proc.pid)
+            added = True
+
+    return descendants
+
+
+def find_candidates() -> list[Candidate]:
+    """Scan all running processes and return orphaned AI agent candidates, oldest first."""
+    current_tree = get_current_process_tree()
+    all_processes = _parse_process_list()
+
+    candidates: list[Candidate] = []
+    for proc in all_processes:
+        if proc.pid in current_tree:
+            continue
+
+        for checker in _CHECKERS:
+            candidate = checker(proc)
+            if candidate:
+                candidates.append(candidate)
+                # only match the first applicable category
+                break
+
+    # collect child processes of all matched candidates
+    candidate_pids = {c.pid for c in candidates}
+    candidates_by_pid = {c.pid: c for c in candidates}
+    descendants = _collect_descendants(candidate_pids, candidates_by_pid, all_processes)
+    candidates.extend(descendants)
+
+    # oldest first
+    candidates.sort(key=lambda c: c.elapsed_seconds, reverse=True)
+    return candidates

cleanup_orphans-0.1.1/cleanup_orphans/version.py

@@ -0,0 +1,34 @@
+"""Version handling for cleanup-orphans."""
+
+import importlib.metadata
+from pathlib import Path
+
+
+def is_local_source_checkout() -> bool:
+    """Check if the code is running from a local source checkout."""
+    package_dir = Path(__file__).resolve().parent
+    # Since this is a flat layout (module-root = ""), repo root is the parent of the package dir
+    repo_root = package_dir.parent
+
+    return (repo_root / ".git").exists() and (repo_root / "pyproject.toml").exists()
+
+
+def get_version() -> str:
+    """Get the version string, appending .dev if running from source."""
+    try:
+        # Try to get the version of the installed package
+        version = importlib.metadata.version("cleanup-orphans")
+    except importlib.metadata.PackageNotFoundError:
+        # Fallback for local development if not installed
+        version = "0.1.0"
+
+    if not is_local_source_checkout():
+        return version
+
+    if version.endswith(".dev"):
+        return version
+
+    return f"{version}.dev"
+
+
+__version__ = get_version()

cleanup_orphans-0.1.1/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "cleanup-orphans"
+version = "0.1.1"
+description = "Detect and safely terminate orphaned AI agent processes (Cursor, agy, Claude, Codex)"
+keywords = [
+    "agent",
+    "orphan",
+    "process",
+    "cleanup",
+]
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "click>=8.5.0",
+    "pydantic>=2.13.5",
+    "structlog-config>=0.15.0",
+]
+
+[[project.authors]]
+name = "Michael Bianco"
+email = "mike@mikebian.co"
+
+[project.urls]
+Repository = "https://github.com/iloveitaly/python-cleanup-orphans"
+
+[project.scripts]
+cleanup-orphans = "cleanup_orphans.cli:cli"
+python-cleanup-orphans = "cleanup_orphans.cli:cli"
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[tool.pyright]
+exclude = [
+    "examples/",
+    "playground/",
+    "tmp/",
+    ".venv/",
+    "tests/",
+]
+
+[tool.pytest.ini_options]
+addopts = "--cov --cov-report=term-missing --cov-report=html:tmp/htmlcov"
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["cleanup_orphans"]
+
+[tool.coverage.report]
+fail_under = 10
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pyright[nodejs]>=1.1.408",
+    "ruff>=0.15.0",
+    "coverage>=7.13.4",
+    "pytest-cov>=7.0.0",
+    "covdefaults>=2.3.0",
+    "beautiful-traceback>=1.0.2",
+]

cleanup_orphans-0.1.1/pyproject.toml.orig

@@ -0,0 +1,59 @@
+[project]
+name = "cleanup-orphans"
+version = "0.1.1"
+description = "Detect and safely terminate orphaned AI agent processes (Cursor, agy, Claude, Codex)"
+keywords = ["agent", "orphan", "process", "cleanup"]
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "click>=8.5.0",
+    "pydantic>=2.13.5",
+    "structlog-config>=0.15.0",
+]
+authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
+urls = { "Repository" = "https://github.com/iloveitaly/python-cleanup-orphans" }
+
+
+[project.scripts]
+cleanup-orphans = "cleanup_orphans.cli:cli"
+python-cleanup-orphans = "cleanup_orphans.cli:cli"
+
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# avoids the src/ directory structure
+module-root = ""
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pyright[nodejs]>=1.1.408",
+    "ruff>=0.15.0",
+    "coverage>=7.13.4",
+    "pytest-cov>=7.0.0",
+    "covdefaults>=2.3.0",
+    "beautiful-traceback>=1.0.2",
+]
+
+[tool.pyright]
+exclude = ["examples/", "playground/", "tmp/", ".venv/", "tests/"]
+
+[tool.pytest.ini_options]
+addopts = "--cov --cov-report=term-missing --cov-report=html:tmp/htmlcov"
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["cleanup_orphans"]
+
+[tool.coverage.report]
+fail_under = 10