Introduction

When starting a local dev server, the first obstacle encountered most often is EADDRINUSE: address already in use. In agent workflows, this error often appears at the very beginning of a task. The common handling method is very rough: directly killall node or pkill -f node. The result is that other running Node services on the machine are also killed.

However, the process occupying the port is not necessarily one to be killed: it could be a leftover from a previous session, a dev server that is still running normally, or it could belong to another project or system service. In other words, there are three handling paths for EADDRINUSE — reuse, switch port, or precise kill — and the correct approach is to first determine which category it falls into before deciding the action.

dsh-port-guard is a DSH tool that turns this judgment process into a plugin. DSH (DeepSeek Harness) follows the philosophy that “everything is a plugin.” Below is an introduction to its positioning, features, and usage.

What is it

dsh-port-guard is a DeepSeek Harness plugin by PangYiMing, version 0.1.0, under the MIT license. One-sentence positioning: Port occupancy handling — for processes occupying ports, choose reuse, switch port, or precise kill based on the situation.

It solves the problem of transforming the “port occupied” scenario from a rough kill into a reasoned judgment, ensuring that other people’s processes are not mistakenly killed, and that a living dev server is not unnecessarily restarted.

Core Features

Locate and Forensics

./scripts/port-guard.sh 8080

Replace 8080 with the actual occupied port. The script will print the complete identity information of the occupying process: use lsof to locate the process listening on the port, then ps to check the start time, runtime, presence of a control terminal, %cpu, and rss; use lsof’s cwd to locate which project the process belongs to; finally, use pgrep to check for child processes — do not directly kill the parent process if there are child processes; check the tree first.

Judgment Combinations

How to judge after obtaining forensics information? The README provides several sets of typical judgments:

  • PPID=1: The parent process has exited and has been adopted by launchd — orphan process.
  • tty=??: No control terminal, not run by a person in a terminal.
  • fd0 → /dev/null and fd1/fd2 → some .log: Fingerprint of nohup cmd > log 2>&1 &, indicating it was started by an agent or script.
  • etime for several days, plus %cpu 0.0, plus rss extremely small: A long-standing zombie watcher, possibly still watching the source code directory, suddenly waking up one day to write artifacts.
  • tty=ttys00X: Started by a person in a terminal window; it is better to ask before killing.

Three Handling Paths

First determine which situation it falls into, then choose the corresponding action; do not blindly kill.

Path A, Reuse. The process occupying the port is the dev server of your own project and is still serving normally; reuse is faster than restarting. Before reuse, confirm the process is still alive; kill -0 only checks, does not kill:

kill -0 "$PID" && echo alive

Path B, Switch Port. The process occupying the port belongs to someone else’s project or is a process that shouldn’t be killed; bypass it instead of forcibly killing it:

PORT=18080 node index.js

Path C, Precise Kill. After confirming it is a zombie or residual process, use the plugin’s kill mode. It will first send SIGTERM to the process to give it a chance to exit gracefully; if not, then SIGKILL:

./scripts/port-guard.sh 8080 --kill

Safety Red Lines

The plugin has five “red lines” built in; these are design constraints rather than relying on user self-discipline:

  1. EADDRINUSE does not equal “should be killed”; first judge whether it should be killed; reuse takes priority over restart.
  2. Never killall node / pkill -f node; only perform precise PID kills to avoid harming other normal services.
  3. Never kill PID < 100; those are system processes.
  4. Do not kill other people’s processes; switch ports to bypass.
  5. When the command line is not understood or it is uncertain what it is, stop and report to the user; do not kill without permission.

Installation and Enablement

Two installation methods. The README notes that the first one is only available after the plugin is published to npm:

# After publishing to npm
dsh plugin --profile demo add dsh-port-guard

# Or install from GitHub
dsh plugin --profile demo add github:PangYiMing/dsh-port-guard

Both commands will install dsh-port-guard into the profile specified by --profile.

Typical Usage

Walk through a real port conflict scenario:

  1. First, locate and gather evidence:
./scripts/port-guard.sh 8080
  1. Check the output for judgment. If it is a dev server left over from your own project’s last session, first confirm it is still alive. If alive, reuse directly without restarting:
kill -0 "$PID" && echo alive
  1. If the process occupying the port belongs to someone else’s project or a system service, switch ports to bypass it and do not touch other people’s processes:
PORT=18080 node index.js
  1. Only proceed with precise kill after confirming it is a zombie or residual process:
./scripts/port-guard.sh 8080 --kill

Applicable Scenarios and Notes

Suitable for agent workflows and developers who frequently start dev servers on their local machines, especially scenarios where multiple projects are running simultaneously on the machine and one does not want a port conflict to escalate into a mistaken kill.

Two notes:

  • The plugin runs with the permissions of the current dsh process, and the kill mode operates on real processes. Before installation, check the source code and license (this plugin is MIT).
  • The judgment rules are references, not a free pass: when encountering a process like tty=ttys00X (indicating “someone is running it in a terminal”), confirm with the user before killing.

Conclusion

The value of dsh-port-guard lies not in the kill itself, but in the judgment before the kill: EADDRINUSE has three paths, and blind killing is just the worst one. By solidifying location, forensics, judgment, and handling into scripts and safety red lines, handling port conflicts no longer relies on luck.

  • Community Directory Page: https://www.skillhub.cn/plugins/PangYiMing/dsh-port-guard (Third-party community directory, not an official app store)
  • GitHub Repository: https://github.com/PangYiMing/dsh-port-guard