EdanStarfire Process Manager
Instructions
CRITICAL RULES
- ALWAYS kill processes by PID — never by name (
pkill,killall) - ALWAYS verify the process identity before killing (is it yours or production?)
- ALWAYS confirm termination after killing
Scripts
Find process on a port
~/.claude/skills/process-manager/scripts/find-port.sh <port>
| Field | Meaning |
|---|---|
PROC_STATUS |
free (port available), in_use (process found), error |
PROCESS_COUNT |
Number of processes on port |
PROCESSES |
One line per process: PID=<pid> CMD=<cmd> USER=<user> |
Exit 0 — process(es) found. Present the process info to the user before taking action. Exit 1 — port is free.
Kill a process
~/.claude/skills/process-manager/scripts/kill-pid.sh <PID>
~/.claude/skills/process-manager/scripts/kill-pid.sh <PID> --force # Skip SIGTERM, go straight to SIGKILL
~/.claude/skills/process-manager/scripts/kill-pid.sh <PID> --timeout 10 # Wait 10s before force-killing (default: 5)
| Field | Meaning |
|---|---|
KILL_STATUS |
terminated, failed, not_found, permission_denied |
KILL_METHOD |
SIGTERM, SIGKILL, SIGKILL_fallback |
PROCESS_CMD |
Command name of the killed process |
Exit 0 — process terminated.
Exit 1 — still running after all attempts. Alert user.
Exit 3 — permission denied. Suggest sudo or ask user.
Exit 4 — PID not found (already dead). Inform user, no action needed.
Check if a process is running
~/.claude/skills/process-manager/scripts/check-pid.sh <PID>
| Field | Meaning |
|---|---|
PROC_STATUS |
running or not_running |
PROCESS_CMD |
Command name |
PROCESS_USER |
Owner |
PROCESS_CPU |
CPU usage % |
PROCESS_MEM |
Memory usage % |
PROCESS_ELAPSED |
Time since start |
PROCESS_FULL_CMD |
Full command line |
Exit 0 — running. Exit 1 — not running.
Decision Guidance
Port conflict ("Address already in use")
- Run
~/.claude/skills/process-manager/scripts/find-port.sh <port>to identify what's there - Present process info to user and ask:
- Kill it — if it's a leftover test server, run
~/.claude/skills/process-manager/scripts/kill-pid.sh <PID> - Use different port — if it's a production service or unrelated process
- Investigate — if unclear, run
~/.claude/skills/process-manager/scripts/check-pid.sh <PID>for more detail
- Kill it — if it's a leftover test server, run
Permission denied
The process is owned by another user or requires elevated privileges.
- Suggest running with
sudoif appropriate - Otherwise suggest using a different port
Process won't die (exit 1 from kill-pid.sh)
The process survived both SIGTERM and SIGKILL. This is rare.
- Alert the user — may need manual intervention
- Could be a zombie process (parent needs to reap it)
- Could be stuck in uninterruptible I/O (disk/NFS issue)