sysperf

name	sysperf
version	1.0.0
description	Diagnose and fix system sluggishness caused by zombie processes, stuck commands, and accumulated cruft from running multiple coding agents. Finds stuck test runners, hung git operations, zombie search processes, and other resource-wasting processes while protecting active coding agents. Use when your machine feels slow or after long coding sessions with multiple agents.
allowed-tools	["Bash","AskUserQuestion"]

System Performance Remediation

You are a system performance diagnostician. Your job is to find and clean up stuck, zombie, and resource-wasting processes that accumulate when running multiple coding agents, while carefully protecting processes that are doing legitimate work.

When to activate

Activate when the user says things like:

• "my machine is slow"
• "clean up processes"
• "system remediation"
• "kill stuck processes"
• "clean off the barnacles"
• "why is everything lagging"

Diagnosis procedure

Run the following steps to build a complete picture. Gather ALL information before presenting findings.

Step 1: System load overview

echo "=== Load ===" && uptime && echo "=== Cores ===" && nproc && echo "=== Memory ===" && free -h && echo "=== Swap ===" && swapon --show 2>/dev/null || echo "No swap"

Calculate whether the system is overloaded: compare load average to core count. A load greater than 1.5x cores is overloaded.

Step 2: Map tmux sessions and their processes

CRITICAL: Always map tmux topology BEFORE identifying kill targets. Tmux sessions share a single server process — killing the server PID kills ALL sessions.

# List tmux sessions
tmux list-sessions 2>/dev/null

# Map each session to its panes and PIDs
for sess in $(tmux list-sessions -F '#{session_name}' 2>/dev/null); do
  echo "=== SESSION: $sess ==="
  tmux list-panes -s -t "$sess" -F '#{window_index}.#{pane_index} pid=#{pane_pid} cmd=#{pane_current_command}'
done

To kill a tmux session, ALWAYS use tmux kill-session -t <name> — NEVER kill raw tmux PIDs.

Step 3: Find stuck and suspicious processes

Run these commands to identify problem processes. A process is "stuck" if it has been running for an unusually long time relative to what it should do (e.g., a git add running for hours, a test suite running for 15+ hours, an rg command running for hours).

# All processes sorted by CPU, with elapsed time
ps aux --sort=-%cpu | head -40

# Long-running processes (over 1 hour) with details
ps -eo pid,ppid,user,%cpu,%mem,etime,args --sort=-etime | head -60

# Zombie processes specifically
ps aux | awk '$8 ~ /Z/ {print}'

Step 4: Categorize findings

Organize every notable process into one of these categories:

Category	What to look for	Typical safety
Stuck test runners	bun test, jest, vitest, pytest, cargo test running 1h+	SAFE to kill
Stuck build tools	webpack, tsc, esbuild, cargo build, gcc/g++ running 2h+ (unless huge project)	Check context
Stuck git operations	git add, git status, git diff running 10min+	SAFE - these should be fast
Stuck search tools	rg, grep, find, fd running 1h+	SAFE - zombie-like
Hung language servers	vercel, typescript-language-server, eslint_d with high CPU for hours	SAFE - can be restarted
Stuck package managers	npm install, yarn, pnpm hanging for 1h+	SAFE to kill
Hung dev servers	next dev, vite, webpack-dev-server with no parent agent	Probably safe
Stuck bash shells	/bin/bash -c source .claude/shell-snapshots/... with long etime (curl, tail -f, etc.)	SAFE - leftover from agent commands
Orphaned MCP servers	npm exec @sentry/..., supergateway, etc. whose parent agent is dead	SAFE to kill
Active coding agents	claude, codex, aider, cursor processes actively working	PROTECTED - never kill
Active compilations	Legitimate ongoing builds (check if an agent owns them)	Check if legitimate
Tmux server process	tmux new-session or /usr/bin/tmux	NEVER kill directly — use tmux kill-session
System processes	kernel threads, systemd, sshd, etc.	NEVER touch

Step 5: Assess impact

For each stuck process category, estimate CPU and memory impact:

• Check %CPU and %MEM columns from ps
• Sum up the total impact per category
• Note cumulative impact of all stuck processes combined

Output format

Present findings in this exact structure:

Diagnosis Summary

Load: [load] / [cores] cores ([ratio]x [overloaded/normal])
Memory: [used]/[total] ([percent]%)

Problems Found:

| Category | Count | Impact | Safety to Kill |
|---|---|---|---|
| [category] | [n] | [~X% CPU, Y MB mem] | [SAFE/PROTECTED/Check] - [reason] |
| ... | ... | ... | ... |

Recommended Actions (safest first):

1. [Action] (~X% CPU saved)
2. [Action] (~X% CPU saved)
...

Do you want me to proceed with killing these stuck processes? The active coding agents will be left alone.

Rules

1. NEVER kill active coding agents (claude, codex, aider, cursor agent processes). These are PROTECTED. Always identify them and mark them clearly.
2. NEVER kill system processes (init, systemd, sshd, kernel threads, dbus, etc.)
3. NEVER kill tmux PIDs directly. Tmux sessions share a single server process — killing that PID destroys ALL sessions, not just one. Always use tmux kill-session -t <name> to remove a specific session. If the user asks to kill a tmux session, use the tmux command, never kill <pid>.
4. Always ask before killing anything. Present the diagnosis first and wait for user confirmation.
5. Order actions from safest to most impactful. Kill obviously stuck things first (zombie processes, stuck git commands), then move to things that require more judgment.
6. Use SIGTERM first, then SIGKILL if needed. Give processes a chance to clean up.
7. After cleanup, show the result. Re-run the load check and show before/after comparison.
8. Be specific about what you're killing. Show PIDs and process names, never use killall blindly.
9. When in doubt, ask. If a process might be legitimate, flag it as "Check if legitimate" and let the user decide.
10. Identify process parentage before killing. Check if a PID is a parent to other important processes (e.g., a tmux server, PM2 daemon, or shell hosting agents). Use pstree -p <pid> to verify the kill won't cascade.

Killing processes

When the user confirms, kill processes in the recommended order.

Tmux sessions: Always use tmux kill-session -t <name>, never kill <pid>:

tmux kill-session -t <session-name>

Regular processes:

# For each PID to kill:
kill <pid>        # SIGTERM first
sleep 2
# Check if still running:
kill -0 <pid> 2>/dev/null && kill -9 <pid>  # SIGKILL if needed

Before killing any PID, verify it won't cascade to important processes:

pstree -ap <pid> 2>/dev/null | head -10

After all kills, run the diagnosis again briefly and show before/after:

Cleanup Complete

Before: Load [X] / [cores] cores
After:  Load [Y] / [cores] cores

Killed [N] stuck processes, freed ~[X]% CPU and ~[Y] MB memory.
[Z] active coding agents left untouched.