zombie-hunter

---
name: zombie-hunter
description: Find and kill orphaned processes from previous Claude Code sessions, MCP servers, or bot instances. Use when the user mentions "zombie process", "high CPU", "something is eating my CPU", "kill old processes", "clean up processes", "409 conflict", "polling conflict", or when debugging MCP connection issues. Also proactively suggest this when MCP servers show connection problems or when multiple sessions may have left orphaned processes behind.
user-invocable: true
allowed-tools:
  - Bash
---

# /zombie-hunter — Find and Kill Orphaned Processes

Arguments passed: `$ARGUMENTS`

## What This Solves

When Claude Code sessions end unexpectedly (crash, forced kill, broken pipe), MCP server processes can survive as orphans. These zombies consume CPU, compete for resources (e.g., Telegram bot polling slots causing 409 Conflicts), and cause mysterious failures in new sessions.

## Workflow

### Step 1: Scan for Suspicious Processes

Run these scans and collect results:

```bash
# MCP server processes (bun, node) that might be orphaned
ps aux --sort=-%cpu | grep -E '(bun|node).*(server|mcp|telegram|discord|slack)' | grep -v grep

# High CPU processes from Claude-related tools
ps aux --sort=-%cpu | head -20

# Check for processes whose parent is init/systemd (orphaned)
ps -eo pid,ppid,pcpu,pmem,etime,args --sort=-%cpu | awk '$2 == 1 || $2 ~ /^1[0-9]{3}$/' | grep -E '(bun|node|claude)'

# Check for multiple instances of the same MCP server
ps aux | grep -E 'server\.ts|server\.js' | grep -v grep
```

### Step 2: Analyze Each Suspect

For each suspicious process, determine:
- **Is it orphaned?** Parent PID is 1 (init) or a systemd user process
- **Is it a zombie?** High CPU with no useful work (check stdin/stdout file descriptors)
- **Is it competing?** Multiple processes from the same MCP server directory
- **How old is it?** Check elapsed time — old MCP processes are likely zombies

Check file descriptors for broken pipes:
```bash
ls -la /proc/<PID>/fd/ 2>/dev/null
```

### Step 3: Report Findings

Present findings in a clear table:

| PID | Process | CPU% | MEM% | Age | Parent | Status | Recommendation |
|-----|---------|------|------|-----|--------|--------|----------------|

Status categories:
- **ZOMBIE** — Orphaned, high CPU, broken stdin — safe to kill
- **COMPETING** — Multiple instances of same server — kill all but newest
- **SUSPICIOUS** — Might be orphaned, needs confirmation
- **HEALTHY** — Active, properly parented — leave alone

### Step 4: Kill (with confirmation)

For each ZOMBIE and COMPETING process, ask the user for confirmation before killing. Present the kill commands but don't execute without approval.

```bash
kill <PID>  # Graceful first
# If still alive after 5 seconds:
kill -9 <PID>  # Force kill
```

After killing, verify the process is gone and report freed resources.

### Step 5: Prevention Tips

After cleanup, suggest:
- Check for zombies after unexpected session exits
- Use `claudet` (or whatever alias) to ensure clean launches
- Consider running `/zombie-hunter` at the start of new sessions if experiencing connection issues

## Quick Mode

If `$ARGUMENTS` contains "auto" or "quick", skip confirmation and kill all ZOMBIE-status processes automatically. Still report what was killed.