claude-proc-cleanup

claude-proc-cleanup

A Claude Code plugin that reaps leaked child processes on macOS — orphan MCP servers, dead Claude Code CLI subprocesses, and uv-archived Python servers left behind when a session crashes.

Repo: github.com/pueding/claude-proc-cleanup · Issues / discussion: open an issue

Why this exists

Two specific leak patterns accumulate on a Claude-Code-heavy macOS box, and neither is reclaimed by the OS or by Claude itself:

1. Crashed or abandoned Claude Code sessions leave orphan MCP servers. When a claude process dies abnormally — kill -9, OOM, terminal closed without stdin closing, hung wrapper — its child MCP servers (npm exec chrome-devtools-mcp, npm exec mcp-remote …, uv-archived Python servers, etc.) get reparented to launchd (PID 1) and keep running indefinitely. Each one is a chromium-headless instance, an HTTP bridge, or a long-lived Python process — not cheap.

2. Claude Desktop routines never garbage-collect their subprocess trees. Every time a scheduled "routine" fires, Claude Desktop spawns a fresh disclaimer → claude → MCP servers tree (~5 processes). The routine completes in seconds, but the subprocess tree stays alive forever, until you quit Claude Desktop. One routine firing hourly = ~120 leaked processes per day.

After a few days, a typical machine accumulates hundreds of idle Claude-related processes consuming RAM, file descriptors, and (for the chromium-based MCP servers) GPU memory. This plugin reaps them safely.

Before and after

A real snapshot from the author's machine before installing this plugin:

$ ps -Ao etime=,command= | grep -E 'claude|mcp|chrome-devtools' | wc -l
237

$ ps -Ao etime=,command= | grep '/Helpers/disclaimer' | awk '{print $1}' | sort | head
01-00:19:24
01-01:19:22
01-02:19:22
01-03:19:23
01-04:19:23
01-05:19:23
…   # (every hour at the :19 mark = a scheduled routine firing for 30+ hours)

After running /cleanup-procs --routines:

$ /cleanup-procs --routines

Tree  root=2365  age=01-08:55:30  procs=5
  2365   /Applications/Claude.app/Contents/Helpers/disclaimer …
  2366     claude --output-format stream-json --verbose …
  2386     npm exec chrome-devtools-mcp@latest
  2388     npm exec mcp-remote https://www.example.com/mcp …
  3112       node /Users/me/.npm/_npx/…/mcp-remote …

Tree  root=3044  age=20:19:22  procs=5
  …

(24 more trees)

Total: 26 trees, 130 processes (would kill in non-dry-run).

Kill all 26 trees (130 processes total)? [y/N] y
Reaped 130 processes across 26 trees.

$ ps -Ao etime=,command= | grep -E 'claude|mcp|chrome-devtools' | wc -l
12     # only the active session + its current MCP children

The default-mode SessionStart hook handles scenario #1 silently on every Claude Code launch, no input needed. The --routines slash command handles scenario #2 on demand.

What it does

• Auto-cleanup on session start: a SessionStart hook silently reaps known-leaked processes whose parent has died (PPID==1) and that match a curated allowlist.
• /cleanup-procs slash command: prints a table of candidates, asks for confirmation, then reaps.
• Conservative by default: only kills processes whose parent is launchd (PPID==1), match a specific executable+path/argv pattern, are at least 60 seconds old, and aren't in the current shell's process group.
• --aggressive mode (slash command only) walks live Claude Code session trees and reaps pattern-matching processes not in any tree — useful when a wrapper hangs around as defunct.
• --routines mode (slash command only) targets disclaimer-rooted agent session trees under live Claude Desktop — useful for cleaning up scheduled routines that fired but never released their subprocess tree. Trees older than --min-age (default 120 min) are listed for confirmation.

Install

This repo doubles as a single-plugin Claude Code marketplace. Install via the standard /plugin flow.

From GitHub (recommended):

claude plugin marketplace add pueding/claude-proc-cleanup
claude plugin install claude-proc-cleanup@claude-proc-cleanup

From a local clone (for hacking):

git clone https://github.com/pueding/claude-proc-cleanup.git ~/src/claude-proc-cleanup
claude plugin marketplace add ~/src/claude-proc-cleanup
claude plugin install claude-proc-cleanup@claude-proc-cleanup

The same commands are also available as slash commands inside Claude Code (/plugin marketplace add …, /plugin install …).

After install, the next claude session will auto-run the silent reaper on SessionStart, and /cleanup-procs becomes available.

Uninstall:

claude plugin uninstall claude-proc-cleanup@claude-proc-cleanup
claude plugin marketplace remove claude-proc-cleanup

Customize

Patterns live in patterns.txt. One POSIX ERE per line; # for comments; blank lines ignored.