process-manager

Process Manager

Instructions

When to Invoke This Skill

• Starting background servers for testing
• Finding running processes on specific ports
• Stopping test servers after testing
• Diagnosing port conflicts
• Cleaning up orphaned processes
• Verifying process termination

CRITICAL RULES

DO:

• ✅ Always kill processes by PID (Process ID)
• ✅ Verify PID before killing
• ✅ Use platform-specific commands correctly
• ✅ Confirm process stopped after kill command

DON'T:

• ❌ NEVER kill by process name (pkill, killall, taskkill /IM)
• ❌ NEVER kill by command pattern (pkill -f)
• ❌ NEVER assume process is gone without verification
• ❌ NEVER use generic kill commands without PID

Why? Killing by name/pattern can terminate unrelated processes, including user's production services.

Platform-Specific Commands

Windows

Find Process by Port:

netstat -ano | findstr ":<port>"

Output format:

TCP    0.0.0.0:8001    0.0.0.0:0    LISTENING    12345
                                                  ^^^^^
                                                  PID

Kill Process by PID:

cmd //c taskkill //PID <PID> //F

• /F = Force termination (use //F in Git Bash to prevent path conversion)
• Replace <PID> with actual process ID
• Git Bash Users: Use cmd //c wrapper to prevent Git Bash from converting /PID to a Windows path

Verify Process Stopped:

netstat -ano | findstr ":<port>"

Should return no results.

List All Python Processes:

tasklist | findstr python.exe

Unix/Linux/macOS

Find Process by Port (Method 1 - lsof):

lsof -i :<port>

Output format:

COMMAND   PID  USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
python   12345 user    3u  IPv4  0x123      0t0  TCP *:8001 (LISTEN)
         ^^^^^
         PID

Find Process by Port (Method 2 - netstat):

netstat -tulpn | grep :<port>

Output format:

tcp  0  0  0.0.0.0:8001  0.0.0.0:*  LISTEN  12345/python
                                            ^^^^^
                                            PID

Kill Process by PID:

kill <PID>

Or if process won't die:

kill -9 <PID>

• kill sends SIGTERM (graceful)
• kill -9 sends SIGKILL (immediate)
• Replace <PID> with actual process ID

Verify Process Stopped:

lsof -i :<port>
# or
ps aux | grep <PID>

Should return no results.

List All Python Processes:

ps aux | grep python

Standard Workflows

Starting Background Process

Windows:

start /B <command>

Example:

start /B uv run python main.py --port 8001

Unix/Linux/macOS:

<command> &

Example:

uv run python main.py --port 8001 &

Capture PID on Start (Unix/Linux/macOS):

<command> & echo $!

The $! variable contains the PID of the last background process.

Finding Running Process

By Port:

# Windows
netstat -ano | findstr ":<port>"

# Unix/Linux/macOS
lsof -i :<port>

By Name:

# Windows
tasklist | findstr <name>

# Unix/Linux/macOS
ps aux | grep <name>

By PID:

# Windows
tasklist /FI "PID eq <PID>"

# Unix/Linux/macOS
ps -p <PID>

Stopping Process

1. Find PID (using methods above)

2. Record PID - Write it down or store in variable

3. Kill by PID:

# Windows
cmd //c taskkill //PID <PID> //F

# Unix/Linux/macOS
kill <PID>
# or for force kill:
kill -9 <PID>

4. Verify Stopped:

# Windows
netstat -ano | findstr ":<port>"

# Unix/Linux/macOS
lsof -i :<port>

Handling Port Conflicts

Scenario: Can't start server because port is in use.

1. Find What's Using Port:

# Windows
netstat -ano | findstr ":<port>"

# Unix/Linux/macOS
lsof -i :<port>

2. Identify the Process:

• Is it your test server from previous run?
• Is it production server?
• Is it unrelated process?

3. Decide Action:

• Your test server: Kill it by PID
• Production server: Use different port for testing
• Unrelated process: Use different port or investigate

4. If Killing: Use PID-based kill commands above.

Error Scenarios

"Address already in use"

Error: [Errno 48] Address already in use

Solution:

1. Find process on that port
2. Verify it's safe to kill
3. Kill by PID
4. Retry starting server

"Permission denied" (Unix/Linux/macOS)

Operation not permitted

Cause: Trying to kill process owned by another user

Solution:

• Use sudo kill <PID> (if you have permission)
• Or use different port
• Or ask process owner to stop it

"Access denied" (Windows)

ERROR: Access is denied

Cause: Process requires admin privileges to kill

Solution:

• Run command prompt as Administrator
• Or use Task Manager (Ctrl+Shift+Esc)
• Or use different port

Process Won't Die (Zombie Process)

Unix/Linux/macOS:

# Try graceful first
kill <PID>

# Wait a few seconds
sleep 3

# If still running, force kill
kill -9 <PID>

Windows:

# Already using /F flag which is force kill
cmd //c taskkill //PID <PID> //F

# If still fails, use Task Manager

Monitoring Processes

Check if Process is Running

By PID:

# Windows
tasklist /FI "PID eq <PID>"

# Unix/Linux/macOS
ps -p <PID>

Exit code 0 = running, non-zero = not running

Watch Process Resource Usage

Windows:

# Open Task Manager
taskmgr

# Or command line
wmic process where ProcessId=<PID> get ProcessId,Name,WorkingSetSize,PercentProcessorTime

Unix/Linux/macOS:

# Interactive monitoring
top -p <PID>

# One-time check
ps -p <PID> -o pid,ppid,%cpu,%mem,cmd

Check Process Logs

If process is server with logging:

# Tail logs in real-time
tail -f <log-file>

# Check specific log directory
ls -lt test_data/logs/
cat test_data/logs/error.log

Examples

Example 1: Start and stop test server

Windows:

# Start
start /B uv run python main.py --port 8001

# Find PID
netstat -ano | findstr ":8001"
# Output: ... LISTENING    12345

# Stop
cmd //c taskkill //PID 12345 //F

# Verify
netstat -ano | findstr ":8001"
# No output = success

Unix/Linux/macOS:

# Start
uv run python main.py --port 8001 &
# Capture PID: echo $!
# Output: 12345

# Or find later
lsof -i :8001
# Output: ... 12345 ...

# Stop
kill 12345

# Verify
lsof -i :8001
# No output = success

Example 2: Diagnose port conflict

Problem: Can't start on port 8001

# Find what's using it
# Windows:
netstat -ano | findstr ":8001"
# Unix/Linux/macOS:
lsof -i :8001

# Identify process
# Windows:
tasklist /FI "PID eq 12345"
# Unix/Linux/macOS:
ps -p 12345

# If it's old test server, kill it
# Windows:
cmd //c taskkill //PID 12345 //F
# Unix/Linux/macOS:
kill 12345

# Retry starting server

Example 3: Clean up multiple test processes

Scenario: Multiple test servers running from previous tests

# List all on test port
# Windows:
netstat -ano | findstr ":8001"
# Unix/Linux/macOS:
lsof -i :8001

# For each PID found, kill individually
# Windows:
cmd //c taskkill //PID 12345 //F
cmd //c taskkill //PID 12346 //F
# Unix/Linux/macOS:
kill 12345 12346

# Verify all stopped
# Windows:
netstat -ano | findstr ":8001"
# Unix/Linux/macOS:
lsof -i :8001

Example 4: Graceful shutdown with fallback

Unix/Linux/macOS:

# Try graceful first
kill <PID>

# Wait 5 seconds
sleep 5

# Check if still running
if ps -p <PID> > /dev/null 2>&1; then
  echo "Process still running, force killing..."
  kill -9 <PID>
else
  echo "Process terminated gracefully"
fi

# Verify
ps -p <PID>