Agent Skills
› NeverSight/learn-skills.dev
› port-process
port-process
GitHub用于端口与进程管理，排查占用、终止卡死进程及资源调试。适用场景包括：端口被占用、查找特定PID、强制杀死进程、处理EADDRINUSE错误、跨平台（macOS/Linux）命令差异对比及后台任务控制。
Trigger Scenarios
端口被占用或地址已在使用
查找并终止卡死或僵尸进程
诊断EADDRINUSE错误
跨平台进程管理命令查询
Install
npx skills add NeverSight/learn-skills.dev --skill port-process -g -y
SKILL.md
Frontmatter
{
"name": "port-process",
"description": "Find what's using a port, kill stuck processes, and manage system resources. Use when user mentions \"port in use\", \"what's on port\", \"kill process\", \"lsof\", \"address already in use\", \"EADDRINUSE\", \"zombie process\", \"process management\", \"find PID\", \"free up port\", \"htop\", \"resource usage\", or debugging port\/process issues."
}
Port and Process Management
Find What's Using a Port
# macOS and Linux
lsof -i :3000
# Linux only (faster)
ss -tlnp | grep :3000
# Older Linux systems
netstat -tlnp | grep :3000
# Show all listening ports
lsof -i -P -n | grep LISTEN
ss -tlnp
lsof -i :PORT works on both macOS and Linux and is the most reliable first choice. On Linux, ss is faster and preferred over the deprecated netstat.
Kill a Process
# By PID
kill 12345 # SIGTERM (graceful)
kill -9 12345 # SIGKILL (forced, last resort)
# By port — kill whatever is on port 3000
lsof -ti :3000 | xargs kill
lsof -ti :3000 | xargs kill -9 # forced
# By name
pkill node
pkill -f "next dev"
killall node # macOS/Linux, kills all matching by exact name
The -t flag in lsof -ti outputs only PIDs, making it pipeable to kill.
macOS vs Linux Differences
| Task | macOS | Linux |
|---|---|---|
| Port lookup | lsof -i :PORT |
lsof -i :PORT or ss -tlnp |
| Kill by port | lsof -ti :PORT | xargs kill |
fuser -k PORT/tcp |
| Process tree | pstree PID (install via brew) |
pstree -p PID or ps --forest |
| Network stats | netstat -an (no -p flag) |
ss -tlnp or netstat -tlnp |
| File descriptors | lsof -p PID |
ls /proc/PID/fd or lsof -p PID |
On macOS, ss and fuser are not available. Stick with lsof.
"Address Already in Use" Diagnostic Flow
When you hit EADDRINUSE or "address already in use":
# 1. Find what owns the port
lsof -i :3000
# 2. Check if it's your own stale process
lsof -i :3000 -sTCP:LISTEN
# 3. Get details on the PID
ps -p <PID> -o pid,ppid,user,command
# 4. Graceful kill first
kill <PID>
# 5. Verify it released
lsof -i :3000
# 6. If still stuck, force kill
kill -9 <PID>
# 7. If port is in TIME_WAIT (Linux), you can reuse it
# Add SO_REUSEADDR in code, or wait ~60 seconds
ss -tlnp | grep :3000
If the port is held by a process with PPID 1, it is orphaned. Kill it directly.
Find Processes by Name
# Search running processes
ps aux | grep node
ps aux | grep -v grep | grep node # exclude the grep itself
# Better alternatives
pgrep -la node # list PIDs and command lines
pgrep -f "next dev" # match full command string
pidof node # Linux only, returns PIDs
# Detailed info for a known PID
ps -p 12345 -o pid,ppid,user,%cpu,%mem,etime,command
Process Tree
# Linux
pstree -p 12345 # show tree rooted at PID
ps -ejH # tree view of all processes
ps --forest -eo pid,ppid,cmd
# macOS (install pstree via: brew install pstree)
pstree 12345
# Find parent of a process
ps -o ppid= -p 12345
Useful for finding which shell or supervisor spawned a runaway process.
Background and Foreground
# Run in background
node server.js &
# List background jobs in current shell
jobs
# Bring job #1 to foreground
fg %1
# Send foreground job to background
# Press Ctrl-Z first (suspends it), then:
bg %1
# Detach from terminal (survives logout)
nohup node server.js > output.log 2>&1 &
# Disown an already-running background job
node server.js &
disown %1
# disown makes the shell forget about the job so it won't get SIGHUP on exit
Resource Usage
# Interactive process monitor
top # built-in everywhere
htop # better UI (install separately)
# One-shot: top processes by CPU
ps aux --sort=-%cpu | head -20 # Linux
ps aux -r | head -20 # macOS (sorted by CPU)
# One-shot: top processes by memory
ps aux --sort=-%mem | head -20 # Linux
ps aux -m | head -20 # macOS (sorted by memory)
# Memory summary
free -h # Linux only
vm_stat # macOS (pages, divide by 4096 for bytes)
Disk Usage
# Filesystem overview
df -h
# Size of a directory
du -sh /path/to/dir
# Find large directories (top 10)
du -h /path | sort -rh | head -10
# Interactive disk usage explorer
ncdu /path # install separately, very useful
# Find files over 100MB
find / -type f -size +100M -exec ls -lh {} \; 2>/dev/null
# Docker disk usage (common space hog)
docker system df
docker system prune -a # reclaim space, removes unused images/containers
File Descriptors
# Check current limits
ulimit -n # soft limit for open files
ulimit -Hn # hard limit
# Raise soft limit for current session
ulimit -n 65536
# List open files for a process
lsof -p 12345
lsof -p 12345 | wc -l # count them
# Linux: inspect directly
ls /proc/12345/fd | wc -l
# Find processes with many open files (Linux)
for pid in /proc/[0-9]*; do
echo "$(ls $pid/fd 2>/dev/null | wc -l) $pid"
done | sort -rn | head -10
If a process hits the file descriptor limit, it logs errors like "too many open files." Raise ulimit -n or fix the file/socket leak.
Signals
| Signal | Number | Behavior | When to use |
|---|---|---|---|
| SIGTERM | 15 | Graceful shutdown, process can catch and clean up | Default. Always try first. |
| SIGINT | 2 | Same as Ctrl-C | Interactive stop |
| SIGHUP | 1 | Hangup. Some daemons reload config on SIGHUP. | Reload config (nginx, Apache) |
| SIGKILL | 9 | Immediate termination, cannot be caught | Process ignores SIGTERM |
| SIGSTOP | 19 | Pause process (like Ctrl-Z) | Temporarily freeze a process |
| SIGCONT | 18 | Resume stopped process | Unpause after SIGSTOP |
Always send SIGTERM first. Give it a few seconds. Only use SIGKILL (kill -9) when the process refuses to exit. SIGKILL skips all cleanup -- temp files, lock files, and sockets will be left behind.
kill PID # SIGTERM
kill -HUP PID # SIGHUP (reload)
kill -9 PID # SIGKILL (last resort)
Common Scenarios
Dev server won't start (port taken)
lsof -ti :3000 | xargs kill
# then restart your server
Orphaned Node.js process eating CPU
pgrep -la node
# identify the stale one by its command line
kill <PID>
Multiple stale dev servers
# Kill all node processes (careful in production)
pkill -f "next dev"
pkill -f "vite"
pkill -f "react-scripts"
Out of disk space
df -h # confirm which volume is full
du -h /home --max-depth=2 | sort -rh | head -20 # find biggest dirs
# Common culprits:
docker system prune -a # unused Docker data
rm -rf node_modules/.cache # build caches
npm cache clean --force # npm cache
Zombie processes
# Find zombies
ps aux | awk '$8=="Z"'
# Zombies can't be killed directly -- kill their parent instead
ps -o ppid= -p <ZOMBIE_PID>
kill <PARENT_PID>
A zombie is a process that finished but whose parent hasn't read its exit status. Killing the parent lets init/systemd reap it.
Version History
- e0220ca Current 2026-07-05 20:44
