process-guardian

---

---

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:

1. Session tracking: Check for orphans from previous crashed sessions and kill verified ones
2. Allowlist scan: Scan for orphan processes (ppid=1) matching known patterns and kill them
3. 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:

1. SessionStart: Snapshots current PPID=1 processes as baseline
2. PostToolUse(Bash): After each Bash call, diffs against baseline → records new orphans
3. SessionEnd: Marks .clean exit
4. 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