Overview
Claude Code plugin for auto-cleanup of orphan processes from AI coding sessions.
The problem:
- When running multiple agents or MCP servers, unexpected exits happen—OOM kills, session crashes, failed startups
- These leave orphan processes behind, some silently consume 100% CPU in the background
- Others go unnoticed until your machine freezes—manual cleanup gets old fast
What it does:
- Automatically cleans up orphan Claude subagents and MCP servers on session start (allowlist)
- Tracks processes spawned by Bash tool calls and cleans up orphans from crashed sessions (session tracking)
- Provides
/check command for manual process management
- Supports macOS, Linux, and Windows
Key principle:
- Two-layer defense: allowlist for known patterns + session tracking for arbitrary scripts
- Allowlist-only for known processes—unknown processes are completely ignored
- Session tracking catches anything spawned via Bash tool that becomes orphaned after a crash
Installation
claude plugin marketplace add ibarapascal/process-guardian
claude plugin install process-guardian@process-guardian
That's it. The plugin runs automatically on every session start.
Usage
Automatic (Default)
Just start a new Claude session. Process Guardian will:
- Session tracking: Check for orphans from previous crashed sessions and kill verified ones
- Allowlist scan: Scan for orphan processes (ppid=1) matching known patterns and kill them
- Report what was cleaned (or a friendly status message)
During your session, PostToolUse(Bash) hook silently tracks new PPID=1 processes (~50ms overhead per Bash call). On clean exit, tracking data is marked as clean. On crash/Ctrl+C, next session auto-cleans.
Manual
/check
Scans and displays both tracked session processes and allowlist-matched orphan processes with options to kill specific ones.
Safety: Allowlist-Only
Your normal processes are never touched.
| Approach | Unknown Process | Risk |
|---|
| Blocklist | Might get killed | High |
| Allowlist | Ignored | None |
What Gets Killed
Only these specific patterns:
claude --* (subagents with arguments)@modelcontextprotocol/server-*@playwright/mcp, playwright-mcp@upstash/context7-mcp- Browsers with
--remote-debugging-port or ms-playwright
What's Safe
- Your browsers (Chrome, Firefox, Safari)
- Your Electron apps (VS Code, Slack, Discord)
- Your dev servers (webpack, vite, next)
- Everything not in the allowlist
How It Works
Layer 1: Allowlist Scanning (SessionStart)
Scans PPID=1 processes and kills those matching known patterns (Claude subagents, MCP servers). Fast and deterministic.
Layer 2: Session PID Tracking (PostToolUse → SessionStart)
Tracks processes spawned by Bash tool calls:
- SessionStart: Snapshots current PPID=1 processes as baseline
- PostToolUse(Bash): After each Bash call, diffs against baseline → records new orphans
- SessionEnd: Marks
.clean exit
- Next SessionStart: Crash (no
.clean) → kills tracked orphans with triple verification (PID + start time + command)
This catches arbitrary scripts (Python, Node, etc.) that allowlist can't cover.
Platform Support
