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
uv tool install cleanup-orphans
Or add to an existing project:
uv add cleanup-orphans
Usage
Launch interactive multi-select via fzf:
cleanup-orphans
Print candidates in a dry-run table:
cleanup-orphans --list
Terminate all identified candidates after confirmation:
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
fzfwith 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
This project was created from iloveitaly/python-package-template
1 maintainer
Metadata
1 maintainer
Release files for cleanup-orphans 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| cleanup_orphans-0.1.1.tar.gz | 8.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| cleanup_orphans-0.1.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 18.6 kB
Release files / cleanup_orphans-0.1.1.tar.gz
| Download URL | cleanup_orphans-0.1.1.tar.gz |
|---|---|
| Size | 8.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fdda25f87f74695dd0fe03563045e34b9e06b3948effee0a9cce633041393b16
|
|
BLAKE2b-256 checksum How to use checksums |
0bc2488ea5df343b0727e5879954ecc0c2c5bca2254e671f4bb40a90a5eca0e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / cleanup_orphans-0.1.1-py3-none-any.whl
| Download URL | cleanup_orphans-0.1.1-py3-none-any.whl |
|---|---|
| Size | 10.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
74198f343ad5f53fd8981de96fa46d1b978225319682dbed21cd9ee3d814b1e2
|
|
BLAKE2b-256 checksum How to use checksums |
90ada11812dcba4e3abc0c24266b267f655c7bcfa6fbcf93692e589d5f8a8873
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.19 {"installer":{"name":"uv","version":"0.12.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
